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INTRODUCTION 


TSX-Plus is a high-performance operating system for Digital Equipment C° r P 
ration PDP-11 and LSI-11 computers supporting up to 31 concurrent time sharing 
users. TSX-Plus provides a multi-user programming environment that is simi ar 
to extended-memory (XM) RT-11. 

1. TSX-Plus keyboard commands are compatible with those of RT-11. 

2. TSX-Plus supports most RT-11 system service calls (EMTs). 

3. Most programs that run under RT-11 will run without modification 
under TSX-Plus. This includes RT-11 utility programs such as PIP, 
DUP, DIR, LINK, and MACRO. 

4. TSX-Plus uses RT-11 XM version device handlers. 

5. TSX-Plus provides PLAS extended memory services such as virtual 

overlays and virtual arrays, as well as support for extended memory 
regions. 

TSX-Plus can simultaneously support a wide variety of jobs and programming 
languages including COBOL-Plus, FORTRAN, BASIC, DIBOL, DBL, Pascal, C, MACR , 
TECO and KED. TSX-Plus is used in educational, business, scientific and 
industrial environments. It can concurrently support commercial users doing 
transaction processing, engineering users performing scientific processing, 
system programmers doing program development, and real-time process control. 

Numerous application software packages compatible with TSX-Plus are available 
from other vendors. 

TSX-Plus supports RT-11 system service calls (EMTs) as its basic mode of 
operation. The result is low system overhead and substantially improve 

performance over systems that emulate RT-11 services. TSX Plus overlaps 
terminal interaction time, I/O wait time, and CPU execution time for all jobs 
on the system. The result is a tremendous increase in the productivity of the 
computer system. 

In addition to the basic RT-11 functionality, TSX-Plus provides extended 

features such as: shared file record locking; inter-job message communication, 
program performance monitoring; command file parameters; logon and usage 
accounting; directory and data caching; multitasking; and system I/O buffering. 

This manual describes all the features unique to TSX-Plus as well as; any 
differences from RT-11. Many of the special features of TSX Plus are available 
as EMTs available to the MACRO programmer. Access to these features from other 
languages requires the appropriate subroutine interfacing. 

TSX-Plus will run on any PDP-11 or LSI-11 computer with memory management 
hardware and at least 128Kb of memory. The system must also have a disk 
suitable for program swapping (the swapping disk can be used for regu ar i e 
storage as well). Time-sharing lines can be connected to the system through 
DL-11^ or DZ-11 communication devices. Both hard-wired and dial-up lines are 
supported by TSX— Plus. 





Introduction 


MANAGEMENT OF SYSTEM RESOURCES 
Memory Management 

TSX-Plus uses the memory management facilities of PDP-11 computers to keep 
several user jobs in memory simultaneously and switch rapidly among them. 
TSX-Plus protects the system by preventing user jobs from halting the machine 
or storing outside their program regions. TSX-Plus provides several ways to 
control the amount of memory used by individual jobs. Programs may be allowed 
to use up to 64Kb of memory and, if additional space is needed, may also use 
extended memory regions, virtual overlays and virtual arrays. The system 
manager may enable job-swapping to accommodate more user jobs than can fit in 
existing memory. 

Execution Scheduling 

TSX-Plus provides fast response to interactive jobs but minimizes job-swapping 
by use of an efficient job-scheduling algorithm. TSX-Plus permits job 
scheduling on both an absolute priority basis and by a method based on job 
states. For most applications, the method based on job states is preferred. 
The state-driven method provides the most transparent time-sharing scheduling, 
suitable for interactive environments. The absolute priority method always 
runs the highest priority executable job, when not servicing interrupts, 
regardless of that job's state. This state-free method is most suitable for an 
environment in which several real-time jobs must be assigned absolute priori¬ 
ties. TSX-Plus permits both kinds of jobs to co-exist in the same system, with 
interactive jobs being scheduled whenever higher priority state-free jobs are 
not executing. 

Job priorities may be assigned over a range of 0 to 127. The lowest priority 
jobs, typically 0 to 19, are reserved for fixed priority jobs which can soak up 
system idle time without disturbing interactive or real-time jobs. The medium 
priority range, typically 20 to 79, is assigned to interactive jobs which are 
scheduled according to a unique and efficient algorithm which makes time¬ 
sharing nearly transparent to several users. The highest priority range, 
typically 80 to 127, is reserved for jobs which must execute according to a 
rigid priority scheme such as might be found in a real-time environment. In 
addition, real-time jobs may execute interrupt service routines at fork level 
processing or schedule interrupt completion routines to run as fixed—high- 
priority jobs. 

Job scheduling is controlled by several system parameters relating job 
priorities, system timing and other events. The TSX-Plus System Manager s 
Guide includes a more complete description of job priority and scheduling. 

Directory and Data Caching 

TSX-Plus provides a mechanism to speed up directory operations by caching 
device directories. This reduces disk I/O necessary to open existing files. 
Caching of file data is also possible to further improve system throughput. 
The information kept in the cache buffers is managed according to a least- 
recently-used algorithm. Directory and data caching are discussed in the 
System Manager's Guide. 
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System Administrative Control 

TSX-Plus allows the system manager to limit access to the system through a 
logon facility and to restrict user access to peripheral devices. These 
features are described in the TSX-Plus System Manager's Guide. 
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SUMMARY OF CHAPTER CONTENTS 
Starting Time-shar ing Sessions 

Chapter 1 of this manual describes the procedure for starting and stopping a 
time-sharing session with TSX-Plus; the special functions of some control- 
characters; and use of the single line editor for correction of typing errors 
in command lines or data entrv fields. 

Keyboard Commands 

TSX-Plus responds to keyboard commands that are simple and natural (PRINT, RUN, 
COMPILE, TYPE, etc.). TSX-Plus also provides user-definable commands, and 
includes support for a menu driven command interface. Chapter 2 discusses 
command interpretation sequence, user-defined commands, the menu interface and 
lists all TSX-Plus keyboard commands. It provides full descriptions of 
commands unique to TSX-Plus, describes differences between TSX-Plus and RT-11 
commands, and lists the RT—11 commands which are not supported by TSX—Plus. 
Many of the commands are identical to their RT—11 counterparts and the RT 11 
System User's Guide should be consulted for detailed descriptions. 

Command Files 

Frequently used sets of commands may be stored in a disk file and executed by 
invoking the command file. Parameters may be passed to the command file and 
interpreted as though they were included at designated places in the file. 
This provides an alternative way for users to create their own commands. 
Command files are described in Chapter 3. 

Virtual Lines and Detached Jobs 

TSX-Plus provides a facility known as "virtual lines" that allows one time¬ 
sharing user to simultaneously control several programs from a single terminal. 
The user may logically switch among the primary and virtual lines at any time. 
When a program that is not currently connected to a time-sharing line writes 
output to the terminal, the output is stored in a system buffer. When the 
buffer is filled, the program is suspended until the user reattaches to the 
program and accepts the queued output. Virtual lines are useful in situations 
in which it is desirable to run a long "number crunching" job without tying up 
a terminal. Detached jobs are similar, but are not associated with any 
terminal. Virtual lines and detached jobs are discussed in Chapter 4. 

Printer Spooling System 

TSX-Plus provides a convenient and powerful facility for automatic spooling of 
output to line printers and other devices. The spooler may simultaneously 
drive several devices. If the line printer is spooled, then simply directing 
output to device "LP" from a program causes the output to be spooled. A 
spooled file may designate the name of a form on which it is to be printed. 
When a form change is required, the spooled device is suspended and a message 
is sent to the operator requesting the form. After mounting the new form, the 
operator may print a form alignment file. Once a form is mounted, all files 
requiring the form are printed without further operator intervention. The 
operator may also lock a particular form on the printer, preventing automatic 
form change requests. Keyboard commands are provided to check the status of 
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spooled devices, delete files from the output queue, and reprint the most 
recent portion of the current file. Files sent to a spooled device may be 
released to the printer as data becomes available or held until the output file 
is closed. The spooling system is discussed in Chapter 5. 

Program Controlled Terminal Options 

TsX-Plus allows the programmer to modify terminal handling characteristics 
during program execution. For example, a program may disable character 
echoing, use single character activation, use high efficiency output mode, 
enable lower case input, activate on field width, or disable automatic echoing 
of line-feed after carriage-return. These terminal options may be selected 
either by issuing the appropriate EMT request or by writing a special sequence 
of two or three characters to the terminal. Chapter 6 discusses the use of 
terminal options during program execution. 

TSX-Plus EMTs 

TSX-Plus supports most of the system service calls (EMTs) provided by RT-11 
and, in addition, provides many more to utilize the special features of 
TSX-Plus. For example, EMTs are provided to determine the TSX-Plus line number 
and the user name, to send messages to another time-sharing line, to check for 
terminal input errors, and to check for activation characters. EMTs related to 
specific features, such as detached jobs or real-time programming, are 
described in the relevant chapters. The TSX-Plus EMTs which are not closely 
related to features described elsewhere are discussed in Chapter 7. 

User Memory Mapping 

TSX-Plus supports the use of extended memory regions through EMT calls 
compatible with those provided by the RT-11 XM monitor. This allows the use of 
virtual overlays and FORTRAN virtual arrays. Users can also expand programs to 
use the full 16-bit virtual address space. That is, by giving up access to the 
I/O page and direct access to fixed offsets in RMON, a program may address a 
full 64Kb. User control of extended memory and virtual job space is discussed 
in Chapter 8. 

Shared Files and Data Caching 

TSX-Plus provides a file sharing mechanism whereby several cooperating programs 
may coordinate their access to common data files. Programs may request 
different levels of shared file access, and control shared access on a 
record-by-record basis. Two methods of data caching are also provided: 1) 
general data caching which is enabled when devices are MOUNTed; and 2) record 
caching which is only available to shared files. Directory caching is also 
enabled by the MOUNT request. This accelerates directory searching for file 
LOOKUPS. The use of shared files and data caching is described in Chapter 9. 

Inter-program Message Communication 

TSX-Plus offers a message communication facility that allows running programs 
to exchange messages. Messages are transmitted through named "message 
channels". A program can queue messages on one or more message channels. 
Receiving programs can test for the presence of messages on a named channel and 
can suspend their execution until a message arrives. A message can be queued 
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for a program that will run at a later time. The message facility is discussed 
in Chapter 10 

Real-time Support 

TSX-Plus provides real-time program support services that allow multiple 
real-time programs to run concurrently with normal time-sharing operations. 
Real-time programs may optionally lock themselves in memory, directly access 
the I/O page, redefine their memory mapping, and connect device interrupts to 
subroutines within the program. Real-time support is discussed in Chapter 11. 

Shared Run-time System Support 

TSX-Plus allows one or more shared run-time systems to be mapped into the 
address space of multiple TSX-Plus time-sharing jobs. This saves memory space 
when multiple users are running the same types of programs (e.g., COBOL-Plus or 
DBL) and can also be used in situations where programs wish to communicate 
through a shared data region. Shared run-time systems are discussed in Chapter 
12 . 

Performance Analysis Facility 

TSX-Plus includes a performance analysis facility that can be used to monitor 
the execution of a program and determine what percentage of the run time is 
spent within certain program regions. When the performance analysis facility 
is being used, TSX-Plus examines the program being monitored at each clock tick 
(50 or 60 times per second) and notes the value of the program counter. On 
completion of the analysis, the TSX-Plus performance reporting program can 
produce a histogram of the time spent in various parts of the monitored 
program. Performance analysis is discussed in Chapter 13. 

Differences from RT-11 

Some inevitable differences exist between RT-11 and TSX-Plus. Chapter 2 

describes the additional keyboard commands provided by TSX-Plus, the minor 
differences in some commands, and the RT-11 keyboard commands not supported by 
TSX-Plus. Some other differences between RT-11 and TSX-Plus may not be 

obvious. The FORMAT utility is not supported. A few system service calls 
(EMTs) behave slightly differently in the two systems and some RT-11 EMTs are 
not supported by TSX-Plus (notably those supporting multi-terminal operations). 
These differences are detailed in Chapter 14. 

Appendices 

Appendix A describes the SETSIZ utility program which may be used to control 
the amount of memory available to programs. Appendix B describes a library of 
subroutines which are available to the DIBOL user to take advantage of some of 
the special features of TSX-Plus. Appendix C describes the FILTIM utility 
which displays directory information about files, including the file creation 
time. Appendix D provides a table of EMT function and subfunction codes, and 

brief descriptions of both RT-11 and TSX-Plus EMTs; these are useful in 

conjunction with the SET EMT TRACE command. Appendix E contains listings of 
common subroutines called by the example programs throughout this manual. 
Appendix F contains explanations of monitor error messages; fatal system error 
messages are covered in the TSX-Plus System Manager's Guide. Appendix G 
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describes the commands and techniques used to work with logical subset disks. 
Appendix H describes job execution priorities. 
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1. BASIC OPERATION 


1.1 Logging on 

Each user coalesces with the ^"er^y 

SSSTKl -K.SSLS 

is first started ’ a greeting 

message will be displayed at the terminal. 

The system manager may^assign a J'fUe°contains U initialization 

time-sharing line is started. ^ start ing execution of some program 

commands for a line. It canend y k board mon itor prompt is a period.) 

or by waiting for a system comman . <• lock a program to a line so that 

It is possible for a start-up command file to lock a ^ ^ ^ 

on termination of the program t e ine Typing control-C will not abort 

optional log-off command file is executed. Typing control 

start-up or log-off command files. 

The system manager may also require log on programmer number) 

system manager assigns each user a user ^ message "’Logon please:" is 

and password. After the greet ng^ mes g^» name (or project .programmer 

printed. The user responds y yp TSX _ plus then requests the password. The 
number) followed by carriage retu * typed. After the user name (or 

password is not echoed to the termina validated TSX-Plus types the 

project,programmer number) system manager^may also designate a 

”start-up” We command*" 0 f ile ct«!l system access and set 

certain operating parameters. 


The following example illustrates a typical log-on sequence, 
typed by the user is underlined. 


The information 


(carriage return pressed) 

( > 

(greeting message) 

( > 

23-Jan-84 13:39:50 

Line #2 


Logon please: JOHNSON 
Password: MYPASS 
Welcome to the system 


(Password is not displayed.) 


(TSX-Plus is now waiting for a system command.) 


A user may adopt a new password while logging on. To do this, enter a slash 
and the new password immedjplow'd. »‘,T f'rom 1 to 7 
t rln ^tranr^rbl^osJ ^ ldtters.. a nd .duus. Th. 
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(carriage return pressed) 

( ) 

(greeting message) 

( ) 

20-Jun-83 14:17:43 

Line #5 

Logon please: 107 > 24 (Either user name or PPN may be used.) 

Password: OLDP/NEWP (Passwords are not displayed.) 

Welcome to the system 


If the system manager has not required "log on account authorization, then the 
system will either execute a start-up command file or simply display the 
monitor prompt (".") and wait for a system command to be entered. 

1.2 Logging off 

The OFF keyboard command is used to terminate ( log off ) a time-sharing 
session. 

The system manager may specify a log off command file to be executed whenever 
a job logs off. Control-C will not abort a "log off" command file. 
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1.3 Control characters 

Certain control characters have special meaning to the system. These "control 
characters" control certain terminal operations. They are entered by holding 
down the "CTRL" key while pressing the selected character. 


CTRL-C 

- Interrupts the current program and returns control to the 
keyboard monitor. If the running program is not waiting for 

input, two successive CTRL-C's are required to interrupt its 
execution. CTRL-C will not interrupt start-up or log-off 

command files. 

CTRL-0 

- Suppresses program output to the terminal until one of the 
following conditions occurs: 

1) A second CTRL-0 is typed 

2) The program returns to the monitor 

3) The running program issues a .RCTRLO EMT 

CTRL-Q 

- Resumes printing on the terminal from the point at which 
printing was previously suspended by CTRL-S. CTRL-Q has no 

special effect if SET TT NOPAGE has been used. 

CTRL-R 

- Causes the current characters in the terminal input buffer to be 
displayed. This can be used to check the actual contents of an 
input line when rubout editing has been done on the line. 

CTRL-S 

- Temporarily suspends output to the terminal until CTRL-Q is 
typed. CTRL-S has no special effect ‘used if the SET TT NOPAGE 
command has been issued. 

CTRL-U 

- Deletes the current input line. 

CTRL-W 

- Used to switch to a TSX-Plus virtual line. (See Chapter 4 for 
more information on virtual lines.) 

CTRL-Z 

- Indicates end-of-file when input is being read from device "TT". 

The normal 

function of these keys may be altered during program execution. 


Chapter 6 describes program controlled terminal options that influence these 
functions. When enabled, the single line editor defines additional special 
purpose keys; see the next section for further information about the single 
line editor. 
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1.4 Single Line Editor 

It is often desirable to correct typing mistakes made in the entry of command 
input lines or to correct data entry fields while executing some program. This 
can be done to a limited extent by use of the DELETE and Ctrl-U keys, however 
much more editing capability is available if the Single Line Editor facility 
is used. To use the single line editor, the system manager must enable it 
during the TSX-Plus system generation process. In addition, it must be turned 
on for each time-sharing line before use. To use the single line editor, issue 
the command: 

SET SL ON 

either in a start-up command file or as a keyboard command. The single line 
editor may be used only with VT100 or VT52 type terminals. 

Several other SET options are available for use with the single line editor. 
These are described in Chapter 2 in the section on keyboard commands. 

The single line editor accepts special key commands to direct its operation. 
Under TSX-Plus, there are two modes of operation of the single line editor: 
normal mode (RT-11 compatible); and KED mode. In normal mode, the TSX-Plus 
single line editor is compatible with the RT—11 single line editor except for 
the differences noted in the table at the end of this section. The following 
tables summarize the functions performed by the editing control keys. 
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Single Line Editor Key Functions 
Normal (RT-11 compatible) Mode 



Primary Key Functions 

(Not prefixed by PFl) 

i 

Key 

i 

Function 

i 


Up arrow 

I Retrieve previous input lines 


Down arrow 

I Retrieve line from save buffer 


Left arrow 

I Move cursor left one character 


Right arrow 

I Move cursor right one character 


BACK SPACE 

1 Exchange char under cursor with char to right 

DELETE 

| Delete character to left of cursor 


LINE FEED 

| Delete word to left of cursor 


RETURN 

| Pass current line to running program 


PFl 

| Used before other keys to perform second 

function 

PF2 

I Not implemented 


PF3 

I VT52: Delete from cursor to right end of 

line 

PF4 

| VT100: Delete from cursor to right end of 

line 

Ctrl-U 

I Delete from cursor to left end of line 


Ctrl-R 

| Redisplay current line 



+- 



+- 

i 

Secondary Functions (Keys Prefixed by PFl) 

i 

+- 

1 Key 

H- 

Function 

i 


Up arrow 
Down arrow 
Left arrow 
Right arrow | 
BACK SPACE I 
DELETE I 

LINE FEED | 
RETURN I 

PF1 
PF2 
PF3 
PF4 

Ctrl-U I 


Retrieve previous input lines (PF1 is ignored) 

Save current line in "save buffer" for recall later 

Move cursor to left end of line 

Move cursor to right end of line 

Exchange char under cursor with char to left 

Retrieve last deleted character 

Retrieve last deleted word 

Truncate from cursor to end of line and execute 

Ignored 

Not implemented 

VT52: Retrieve last deleted line 
VT100: Retrieve last deleted line 
Retrieve last deleted line 
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In addition to the normal (RT-11 compatible) mode of operation for the single 
line editor, TSX-Plus also permits use of some of the keypad functions in a 
fashion similar to KED (or K52). These keypad operations are available in 
addition to the functions described above for the single line editor. In order 
to use the extended (KED) mode with the single line editor, issue the following 
command: 

SET SL KED 

When the KED mode is enabled, the following tables describe the additional 
functions available to the single line editor. 

Single Line Editor Key Functions 


KED Mode 


+— 

1 


Primary Key Functions (Not prefixed by PFl) 

i 

H— 
1 

Key 

| Function 


-1- - 

l 

0 

! Move cursor to left end of line 

i 

l 

1 

| Move cursor one word in current direction 

i 

l 

2 

| Move to end of line in current direction 

i 

1 

3 

| VT100: Move cursor one char in current direction 

i 

1 

4 

j Set direction forward (left to right) 

i 

l 

5 

I Set direction backward (right to left) 

i 

1 

6 

| VT52: Delete character under cursor 

i 

l 

7 

| Not implemented 

i 

l 

8 

| Not implemented 

i 

1 

9 

| VT52: Delete word under cursor 

i 

1 

- 

| VT100: Delete word under cursor 

i 

1 

> 

| VT100: Delete character under cursor 

i 

1 

ENTER 

I Pass current line to running program 

i 
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--- 

I Secondary Functions (Keys Prefixed by PFl) | 

+-+-+ 

Key | Function | 

H-H-h 

I 0 | Delete from cursor to right end of line 

I 1 I Change case of char under cursor 

I 2 | Delete from cursor to right end of line 

I 3 | Not implemented 

4 | Move cursor to right end of line 

5 | Move cursor to left end of line 

6 | VT52: Retrieve last deleted character 

I 7 | Not implemented 

I 8 | Not implemented | 

I 9 | VT52: Retrieve last deleted word I 

I VT100: Retrieve last deleted word 
I , | VT100: Retrieve last deleted character 

I ENTER | Truncate from cursor to end of line and execute | 

H-+-+ 


To return the single line editor to the normal mode, issue the command: 
SET SL NOKED 

To disable the single line editor altogether, issue the command: 

SET SL OFF 


In addition to editing command lines, the single line editor may be used to 
edit data entry fields during program execution. However, there are some 
restrictions on such use. If any of the following conditions exist, then the 
single line editor may NOT be used to edit program data fields: 

1) The SET SL OFF command has been issued 

2) Bit 4 (EDIT$, mask 20) is set in the Job Status Word (JSW) 

3) Bit 12 (TTSPC$, mask 10000) is set in the JSW 


4) The program is using high-efficiency terminal mode 

3) The program is using escape sequence activation 

6) Input is being accepted via the .TTYIN EMT (except as below) 
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In order to use the single line editor to edit data entry fields within 
programs which accept input via the .TTYIN EMT, the following command must be 
issued prior to execution of the program: 

SET SL TTYIN 

Since COBOL-Plus programs accept terminal input via the .TTYIN EMT, the 
following steps must be used to edit data entry fields while executing 
COBOL-Plus programs: 

1) SET SL ON 

2) SET SL TTYIN 

3) From within the executing program, CALL M ESCAPE-OFF ,, 

The TSX-Plus single line editor is generally compatible with that provided with 
RT-11, with the following exceptions: 

1) The "Help" key (PF2) is not implemented. 

2) The SET SL LEARN mode is not implemented. 

3) The SET SL ASK option is ignored. (The current TSX-Plus terminal 

type information is used.) 

4) The SET SL SYSGEN option is ignored. 

5) The maximum width of a command line or input field that is accepted 
is 80 characters. The SET SL WIDTH=n option is ignored. 

6) The line feed key deletes the word to the left of the cursor. 

Technically, characters to the left of the cursor are deleted until 
one of the following delimiters is reached: space, tab, comma, or 

equal sign. 

7) The up arrow key can be used to retrieve either of the last two 

lines. Pressing the up arrow key cycles between recalling the last 
input line and the line prior to that. 

8) Using the single line editor with .TTYIN input does not force a new 
line. 

9) The single line editor is implemented as a TSX-Plus overlay region 

and does not require the SL pseudo-device handler. 
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2.1 Keyboard command interpretation 

When a system command line is typed in, TSX-Plus attempts to interpret it by 
sequentially applying the following rules: 

1. If the User Command Interface is in effect, then each time TSX-Plus 
is ready to accept a keyboard command it passes control to the 
current UCI program. The UCI program may be selected with the SET 
KMON UCI[=filnam] command. See the description of SET KMON command 
and the section in this chapter on the User Command Interface for 
more information. 

2. If the command line begins with an "at-sign" ("@"), TSX-Plus attempts 
to execute a command file. If no device is specified with the 
command file name, device ”DK:” is assumed. The default extension 
for command files is "COM". If the SET KMON IND command has been 
issued, command files will execute under the control of the IND 
program. Command files may be specified for execution as normal 
command files, regardless of whether KMON is set IND or NOIND, by 
starting the command with a dollar-sign (e.g. "$@filnam"). Con¬ 
versely, command files can be forced to execute under the IND 
utility, regardless of whether KMON is set IND or NOIND, by typing: 
"IND filnam". 

See Chapter 3 for further information on the execution of command 
files by TSX-Plus. 

3. If user-defined commands have been allowed during TSX-Plus genera- 
I tion, and if UCL is set FIRST either in TSGEN or subsequently by the 

keyboard SET UCL FIRST command, then commands are checked at this 
point to see if they are user-defined commands. However, if the 
first character on a command line is the underline character (" ") 
then the command on that line is not checked to see if it is a 
user-defined command. See the next section for more information on 
user-defined commands. 

4. TSX-Plus next attempts to identify a command as a standard system 
command such as COPY, RUN, EXECUTE, etc. Commands may be abbreviated 
to the minimum number of characters that uniquely specify the name. 
Thus "COP" would be an acceptable abbreviation for COPY, but "CO" 
would not because it could mean COPY or COMPILE. "COPX" also would 
not be identified as a system command. 

5. If user-defined commands have been allowed during TSX-Plus genera¬ 
tion, and if UCL is set MIDDLE either in TSGEN or subsequently by the 
keyboard SET UCL MIDDLE command, then commands are checked at this 
point to see if they are user-defined commands. However, if the 
first character on a command line is the underline character () 
then the command on that line is not checked to see if it is a 
user-defined command. 
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6* If the command has not yet been identified, then TSX-Plus tries to 
find a command file on device "DK:" that has the same name as the 
command keyword. If no such command file is found on "DK: ", TSX-Plus 
looks for the command file on device "SY:". In either case, if the 
SET KMON IND keyboard command has been issued, it will be executed 
under control of the IND program. When a command file is started in 
this fashion (rather than explicitly specifying an at-sign before its 
name), the command file listing is suppressed as if an implied "SET 
TT QUIET" command was executed during command startup. This implied 
listing suppression is temporary in effect and applies only to the 
command file started in this fashion. See Chapter 3 for more 
information on command files. 

7. If a command file cannot be found, TSX-Plus looks for an executable 
program (SAV file) on device "SY:" that has the same name as the 
command keyword. If such a program is found, it is executed as if 
there were an "R" command in front of the program name. Note that 
while both RT-11 and TSX-Plus allow a line of text input to be passed 
to a program with the RUN command by specifying it after the program 
name, TSX-Plus also allows this to be done with the "R" command and 
with an implied "R" command line when the program name is specified 
as the command keyword. See example 6 below. 

8. If user-defined commands have been allowed during TSX-Plus genera¬ 
tion, and if UCL is set LAST either in TSGEN or subsequently by the 
keyboard SET UCL LAST command, then commands are checked to see if 
they are user-defined commands at this point. However, if the first 
character on a command line is the underline character ("_") then the 
command on that line is not checked to see if it is a user-defined 
command. 

9. If a command has not been identified after all the above steps have 
been tried, then it is reported as an unrecognizable command. The 
error message is: 

?KMON-F-Unrecognizable command 
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The following list summarizes the sequence of events which occur in the 
processing of keyboard commands. If a command can be recognized at any of 
these steps, then the appropriate command is executed and the remaining steps 
are skipped. 

Call user command interface if one is active. 

If command begins with "@", execute command file on DK:. 

If UCL FIRST, check for user-defined command. 

Check for system command. 

If UCL MIDDLE, check for user-defined command. 

Check for command file on DK:. 

Check for command file on SY:. 

Check for SAV file on SY:. 

If UCL LAST, check for user-defined command. 

Report unrecognizable command. 

If user-defined command support has not been included in TSGEN, or if the SET 
UCL NONE command has been issued, or if a command line begins with the 
underscore character then the command interpreter never attempts to 

interpret a command as a user-defined command. Attempts to issue user-defined 
commands under these conditions will also be reported as unrecognizable 
commands. 

Examples: 

1. Execute the command file "DK:PURGE.COM". 

. 0PURGE 

2. Run a program named "DUMP" on device "SY:". 

.R DUMP 

3. Run a program named "PAYROL" on device "DX1:". 

.RUN DX1:PAYROL 


4. List all files on "RK1: 
.DIR RK1: 


5. Start a command file "SY:LOADIT.COM" and pass it the parameter string 
"PROG2". 

. LOADIT PR0G2 

6. Execute the program "SY: PIP. SAV" and pass it the input line 
"A. TMP=B . TMP" . 

.PIP A.TMP=B.TMP 


-19- 




















Keyboard Commands 


2.2 User-defined Commands 

It is possible to define your own keyboard commands in terms of system commands 
and other keyboard commands. New keyboard commands may be defined according to 
the following syntax: 

name :== string 

where name” is a 1 to 11 character command keyword which may consist of 
letters, digits, and the underscore symbol and "string” is a string of 

up to 80 characters which defines the body of the command. 

For example, the following command would define the keyword "NOW” as being 
equivalent to the TIME command: 

NOW :== TIME 

Multiple commands may be included in the body of a command definition by 
separating them with the backslash character (”\”). For example: 

NOW :== DATE\TIME 

An up-arrow character may be included in the command body to cause all 

text on the command line following the command keyword to be inserted in the 
command body at the position of the up-arrow. For example, if a command is 
defined as follows: 

NAMES :== DIR/ORDER:NAME ~ 

Then, if this command is invoked by typing: 

NAMES *.MAC 

The resulting command will be equivalent to: 

DIR/ORDER:NAME *.MAC 

More than one up-arrow character may occur in the command body. The parameter 
string specified when the command is invoked is substituted for each occurrence 
of the uj>-arrow character. 

A user defined command may invoke other user-defined commands within its 
definition provided that the definition does not call on itself and provided 
that the other commands are defined at the time the command is issued. For 
example, the following command definitions would be legal: 

NOW :== SHOW DATE\SH0W TIME 
STATUS :== NOW\SYSTAT 
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But, the following pair of commands would cause an infinite loop: 

ONE :== TWO 
TWO :== ONE 

It is possible to allow abbreviation of user-defined commands. To do this, 
place an asterisk character ("*") yithin the keyword at the point of the 
minimum length abbreviation. For example, the definition: 

ST*ATUS :== NOW\SYSTAT 

Would allow the STATUS command to be abbreviated to "STAT” or "ST" but not to 
"S". 

You can specify the order in which the TSX-Plus command interpreter checks for 
user-defined commands by use of the SET UCL command. This command has four 
f o rms: 


SET UCL FIRST 
SET UCL MIDDLE 
SET UCL LAST 
SET UCL NONE 

If the SET UCL FIRST command is used, user-defined commands will be processed 
before system commands. This allows user-defined commands to replace system 
commands but makes the processing of system commands slower. This is the 
required setting only if it is necessary to replace some system commands. 

If the SET UCL MIDDLE command is used, user-defined commands are processed 
after system commands but before checking for command files and SAV files with 
names that match the command keyword. Using this setting, it is not possible 
to replace a system command with a user command, but both system commands and 
user—defined commands are processed relatively quickly. This is the recom¬ 
mended setting unless it is desirable to replace system commands. 

If the SET UCL LAST command is used, a command will not be checked to see if it 
is a user-defined command until after it is checked to see if it is a system 
command, the name of a command file on DK, the name of a command file on SY, or 
the name of a SAV file on SY. Using this setting, it is not possible to 
replace a system command with a user command and user commands cannot have the 
same name as command files or SAV files. System commands are processed quickly 
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands 
is slow. This is the appropriate setting only if user-defined commands are 
desired, but command files already exist whose names would conflict with 
user-defined commands. Existing command files which are short and merely 
execute system commands should be replaced by user-defined commands. 

If the SET UCL NONE command is used, user defined commands are never inter¬ 
preted. In this mode, attempts to invoke user-defined commands will result in 
the error: 
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?KMON-F-Unrecognizable command 

The following list illustrates where the FIRST/MIDDLE/LAST setting causes the 
command interpreter to check for and process user-defined commands: 

FIRST --> 

See if command is a system command 

MIDDLE --> 

Look for command file on DK: with command name 
Look for command file on SY: with command name 
Look for SAV file on SY: with command name 

LAST --> 

See the beginning of this chapter for further information on the command 
interpretation process. 

If an underscore character ) is typed in front of a keyboard command, this 

is a signal to the system that the command is not to be interpreted as a 
user-defined command. For example, if the NOW command has been defined as 
shown above, then the following command will be recognized as a user-defined 
command and will cause the date and time to be displayed: 

NOW 

However, the following command would not be recognized as a user-defined 
command and would be rejected as an undefined command since there is no NOW 
command defined by the system (unless there is a command file or SAV file on 
SY: with the name NOW): 



There are two reasons for using the underscore prefix. If UCL has been set 
FIRST, the underscore prefix can be used to speed up the processing of large 
numbers of system commands that could be present in frequently executed command 
files. For example, the NOW command could be defined as follows to cause it to 
execute faster: 

NOW :== DATE\ TIME 

The second and more important reason for using the underscore prefix is to 
allow user-defined commands to be defined which replace system commands but use 
the system commands in their definitions. (Note that it is necessary to SET 
UCL FIRST to allow system command replacement.) For example, the following 
definition replaces the system DIRECTORY command with a user-defined command 
that has the same name but which always orders the files alphabetically: 

DIR*ECTORY :== DIR/ORDER:NAME ~ 
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If the body of this command were not preceded with the underscore character, 
then it would be a circular definition and cause a futile loop. 

A user-defined command can cause a command file to be executed. However the 
command file invocation must be the last (or only) command defined within the 
body of the command. For example, the following definition causes all BAK 
files to be deleted, and a command file named LOGOFF to be executed when the 
OFF command is used (the LOGOFF command file could end with an " OFF” command 
to do the actual logoff): 

OFF :== DEL *.BAK/NOQ\@LOGOFF 

A user-defined command may be replaced at any time by simply entering a new 
definition for the command. A command may be deleted by entering its name and 
":==" without a command body. For example, the following command deletes the 
definition of the NOW command: 

NOW :== 

The SHOW COMMANDS keyboard command may be used to display a list of all current 
user-defined commands. 

Commands defined by one time-sharing user are "local” to that user and do not 
affect other users. However, when a virtual line is started the virtual line 
"inherits" the user-defined commands that are in effect for the primary line at 
the time that the virtual line is started. User-defined commands created while 
on a virtual line are not available from other virtual lines or from the 
primary line. All user-defined commands for a job are reset (forgotten) when 
the job logs off. 

The system manager must enable user-defined commands by setting the U$CL flag 
in TSGEN and the program TSXUCL.SAV must be on SY: in order to process 
user-defined commands. The maximum number of commands which can be defined by 
any job is set by the UCLMNC command in TSGEN. The default order for inter¬ 
pretation of user-defined commands during command processing is determined by 
the TSGEN parameter UCLORD. This may be overridden by the keyboard command SET 
UCL {FIRST|MIDDLE|LAST|NONE} for individual jobs. 
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2.3 User Command Interface 

The User Command Interface (UCI) allows a user-provided program to take over 
the job of command acquisition from the TSX-Plus keyboard monitor. When UCI is 
enabled, the user-written program will be called by the TSX-Plus keyboard 
monitor each time it is ready to accept a new command. It is then the 
responsibility of the user-written program to prompt for a command and accept 
it from the terminal. The program may then perform the appropriate actions, 
chain to other programs or pass commands on to the keyboard monitor. This 
provides a mechanism for such applications as a command menu. 

UCI is enabled with the command: 

SET KMON UCI[=filnam] 

which may be entered either from the keyboard or in a start-up command file. 
If the optional "=filnam" is omitted, then the keyboard monitor passes command 
control to the program SY:UKMON.SAV. This is appropriate when a common command 
interface is desired for multiple lines. If different command interfaces are 
desired for different lines, then the file name of the appropriate user-written 
command interface may be specified. 

After UCI is enabled, the TSX-Plus keyboard monitor will run the user-written 
UCI program each time it needs a new command. The program must prompt the user 
for a new command, accept the command, process it as desired and may optionally 
pass the command to the TSX-Plus keyboard monitor by doing a "special chain 
exit". A special chain exit is performed by issuing the .EXIT request with bit 
5 (mask 40) set in the job status word and with R0 cleared. Any commands to be 
executed by the keyboard monitor are passed through the chain data area. See 
the RT-11 Programmer's Reference Manual for more information on "special chain 
exits”. Commands passed to the TSX-Plus keyboard monitor in this fashion 
behave as though the keyboard monitor obtained them from a command file. A 
command file name may also be passed to the keyboard monitor by passing a 
command of the form "@name”. If a command file name is passed to the keyboard 
monitor, then it must be the last or only command passed in the chain data 
area. When a command file name is passed in this manner, then all of the 
commands included in the command file are executed by the keyboard monitor 
before returning to the user-written UCI program for another command. 

Keyboard command control may be returned to the TSX—Plus keyboard monitor by 
the command: 

SET KMON SYSTEM 

The following program provides a simple example of the techniques for writing a 
User Command Interface program. This program accepts a command from the 
keyboard and passes it through to the TSX—Plus keyboard monitor if it is a 
legal command. 
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Example: 

.TITLE MYKMON 
.ENABL LC 

> 

; Simple example of User Command Interface 

; Refuses to pass SET KMON SYSTEM, but otherwise does nothing but 
; pass commands thru to KMON. 


.MCALL .PRINT,.EXIT,.GTLIN,.SCCA 


JSW 

= 44 


;Job status word address 

SPXIT$ 

= 40 


;Special exit flag to pass command to KMON 

MONPTR 

= 54 


;Pointer to base of RMON 

SYSGEN 

= 372 


;Offset into RMON of SYSGEN options word 

BEL 

= 7 


;ASCII bell 

BS 

= 10 


;ASCII backspace 

LF 

= 12 


;ASCII line feed 

FF 

= 14 


;ASCII form feed 

CR 

= 15 


;ASCII carriage return 

ESC 

= 33 


;ASCII escape 


.DSABL 

GBL 

;Disable undefined globals 

START: 

.SCCA 

//AREA, #TTS TAT 

;Inhibit control-C abort 


MOV 

@//MONPTR, RO 

;Get pointer to base of RMON 


TST 

SYSGEN(RO) 

;Are we running under TSX? 


BPL 

QUIT 

;Normal exit if not 


MOV 

//TTYPE, RO 

;Point to EMT arg block to 


EMT 

375 

;Get TSX-Plus terminal type 


ASL 

RO 

;Convert to word offset 


CMP 

R0,//4 

;Legal types are unknown, VT52 and VT100 


BLOS 

1$ 



CLR 

RO 

;If not VT52 or VT100, make unknown 

1$: 

MOV 

R0,R1 

;Save terminal type 


.PRINT 

CLRSCR(Rl) 

;Clear the screen 


.PRINT 

//MENU 

;Display simple menu 


MOV 

//SETRUB ,R0 

;Point to EMT arg block to 


EMT 

375 

;Set rubout filler character 

2$: 

.PRINT 

CENTER(Rl) 

;Move to screen center and clear the line 


.GTLIN 

//BUFFER,//PROMPT 

;Accept input line 


CALL 

MATCH 

;See if it^s legal 


BCS 

2$ 

;Repeat if illegal command 


MOV 

#1000,SP 

;Ensure stack pointer safe 


CALL 

MOVCMD 

;Move command from buffer to chain data area 


BIS 

//SPXIT$, 0//JSW 

;Set special chain exit bit in JSW 


CLR 

RO 

;Required for special chain exit 

QUIT: 

.EXIT 


;And pass command to KMON 


; Simple matching. Easy to defeat by inserting extra spaces!!! 
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MATCH: MOV 

#BUFFER,R2 

;Point to beginning of input buffer 

MOV 

#ILLCMD,R3 

;Point to beginning of illegal command 

1$: TSTB 

(R2) 

;At end of input string? 

BEQ 

2$ 

;Yes, matched so far, probably illegal 

CMPB 

(R2)+,(R3)+ 

;No, test through end of illegal string 

BNE 

9$ 

;No match, not illegal command 

CMP 

R3,#ILLEND 

;Past end of illegal command? 

BLO 

1$ 

;No, keep checking 

2$: SEC 


;Strings match, signal illegal command 

BR 

10$ 


9$: CLC 


;Strings don't match, signal legal command 

10$: RETURN 

; Move command 

from input buffer to chain data area. 

MOVCMD: MOV 

//BUFFER, R2 

;Point to beginning of input string 

MOV 

#512,R3 

;Point to chain data area 

1$: MOVB 

(R2)+,R0 

;Get next char 

BNE 

2$ 

;Continue if not nul 

CLRB 

(R3)+ 

;If end of input command 

BR 

9$ 

; then done 

2$: CMPB 

R0,//'\ 

;Command separator? 

BNE 

3$ 

;No, move it 

CLRB 

RO 

;Yes, replace with nul 

3$: MOVB 

RO,(R3)+ 

;Move command into chain data area 

CMP 

R2, //BUFEND 

;Don't want to overflow 

BLO 

1$ 

;Keep moving if characters left 

CLRB 

-1(R3) 

;Mark end of command (ensure it is ASCIZ) 

9$: SUB 

//512,R3 

;How many bytes did we move? 

MOV 

R3,@#510 

;Mark the number for .CHAIN 

RETURN 

AREA: .BLKW 

10 

;GP EMT argument area 

TTSTAT: .WORD 

0 

;Terminal status word for .SCCA 

TTYPE: .BYTE 

0,137 

;EMT arg block to get terminal type 

SETRUB: .BYTE 

0,152 

;EMT arg block to control terminal funtions 

• WORD 

A 

;Function code - set rubout filler 

.WORD 


;Rubout filler = underline 

CLRSCR: .WORD 

CLRUNK,CLR52, 

CLR100 ;Terminal specific screen clears 

CENTER: .WORD 

CNTUNK,CNT52, 

CNT100 ;Terminal specific move and clear 

.NLIST 

BEX 


CLRUNK: .BYTE 

FF,FF,FF,CR,200 ;Emulate clear screen with 3*(8LFs) 

CLR52: .BYTE 

ESC,'H,ESC,'J 

,200 ;VT52 clear screen sequence 

CLR100: .ASCII 

<ESC>/[H/<ESC>/[J/<200> ;VT100 clear screen sequence 

CNTUNK: .ASCII 

<CRXLFXLFXLF>/ /<200> 

CNT52: .ASCII 

<ESC>/Y% / 

;Line 6, column 1 

•ASCII 

<ESC>/K/ 

;Erase to end of line 

.ASCII 

/ / <200> 

;Move to column 6 

CNT100: .ASCII 

<ESC>/[6;6f/ 

;Line 6, column 6 
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MENU: 

.ASCII 

.ASCII 

<ESC>/[2K/<200> ;Erase 
<LFXLFXLF>/ 

entire line 

***** Simple Menu *****/<200> 

PROMPT: 

.ASCII 

<BEL>/Command: 

/ 

ILLCMD: 

.NLIST 

.REPT 

.BYTE 

.ENDR 

.LIST 

.BYTE 

.ASCII 

32. 

BS 

<200> 

/SET KMON SYSTEM/ 

;Backspace to beginning of field 

;End of string 

;Don't permit UCI disable 

ILLEND: 

BUFFER: 

.BLKB 

81. 

;Command line input buffer 

BUFEND: 

.END 

START 
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2.4 Keyboard Commands 

The keyboard commands accepted by TSX-Plus are listed below. Because many 
commands are identical or very similar to those of RT-11, full descriptions are 
only provided for TSX-Plus specific commands and for differences between 
TSX-Plus and RT-11 commands. Users should consult the RT-11 System User's 
Guide for more information on keyboard commands. 


The ACCESS Command 

The ACCESS command is used to restrict user access to a particular set of files 
or devices. It is only valid in start-up command files. Refer to the TSX-Plus 
System Manager's Guide for further information about this command. 


The ASSIGN Command 

The ASSIGN command is used to associate a logical I/O device name with a 
physical device. To simply assign a logical device name to a physical device, 
the form of the ASSIGN command is the same as that under RT-11. For example, 
to assign the logical device name "BIN" to physical device "DX1" the command 
would be: 

ASSIGN DX1 BIN 

The following command would assign logical device "BIN" to a file named "PR0G1" 
on the system device: 

ASSIGN SY:PR0G1=BIN 

It is also possible under TSX-Plus to assign a new logical name to a previously 
assigned logical name. The effect is to assign the new logical name to the 
same physical device to which the previous assign was directed. For example, 
the following sequence of ASSIGNS result in both logical devices "AA" and "BB" 
being assigned to "DLl". 

ASSIGN DLl AA 
ASSIGN AA BB 

The ASSIGN command is frequently used to assign FORTRAN I/O unit numbers to 
selected devices. To assign FORTRAN I/O unit number 1 to the terminal, the 
command would be: 

ASSIGN TT 1 

The TSX-Plus ASSIGN command provides a useful extension. In addition to being 
able to specify a physical device name, the user may specify a file name, 
extension, and size. If a file name and optional size are specified in 
addition to the physical device name, the file name and size follow the device 
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name. For example, the following command assigns FORTRAN I/O unit number 1 to 
a file named "PAYROL" on device "DXO" with a size of 43 blocks: 

ASSIGN DXO:PAYROL[43]=1 

A maximum of fifteen assignments may be in effect at any given time for each 
user. 


The BACKUP Command 

The TSX-Plus BACKUP command has the same form and options as the RT-11 BACKUP 
command. 


The BOOT Command 

The BOOT command attempts to abort TSX-Plus and reboot RT-11. Due to the 
variations in hardware and bootstrap ROMs, this command is unsupported. The 
BOOT command may either reboot RT-11 on your system or simply halt depending on 
your particular hardware configuration. Unlike the RT-11 BOOT command, no 
device or file name may be specified with the TSX-Plus boot command; BOOT 
always attempts to reboot from the system (SY) device. Operator command 
privilege is required to use this command. The BOOT command is equivalent to 
the $STOP command. 


The BYE Command 

The BYE command is used to log off a timesharing line. It is equivalent to the 
OFF command. 


The COBOL Command 

The COBOL command is used to compile a COBOL source program using the COBOL- 
Plus compiler. COBOL-Plus, a product of S&H Computer Systems, Inc., is sold 
separately. The default extension for COBOL source programs is "CBL”; the 
default extension for COBOL object files is "CBJ”. The COMPILE, LINK and 
EXECUTE commands may also be used to compile and execute COBOL programs. 
TSX-Plus will implicitly invoke the COBOL-Plus compiler and CBLINK link program 
if the source program has the extension "CBL" or the object program has the 
extension "CBJ". Switches that can be used with the COBOL command are listed 
below. 
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Switch Meaning 


/ALLOCATE:size 

/ANSI 

/CARD 

/CREF 

/CROSS 

/DCARDS 

/INFORMATION 

/LINENUMBER 

/LIST[:name] 

/NARROW 

/OBJECT[:name] 
/ONDEBUG 
/PRODUCTION 
/RM 

/SEQUENCE 

/SUMMARY 

/WARN 


Specify size of list or object file. 

Produce warning messages for non-ANSI feature use. 
Source program is in card sequence format. 
(Equivalent to /CROSS). 

Produce a cross-reference of the source program. 
Compile lines with "D" in the indicator field. 
Print additional information at compilation end. 
Enable source line information in object listing. 
Produce a source program listing. 

Format the cross-reference for 80 column display. 
Specify name of object file. 

Compile the program for use with the debugger. 

Omit line number tracing and subscript checking. 
Compile RM/C0B0L(*) programs. 

(Equivalent to /CARD). 

Print only error messages on listing device. 
Suppress warning messages. 


See the COBOL-Plus reference manual for further information about the COBOL 
command. 


* RM/C0B0L is a trademark of Ryan-McFarland Corporation. 


The COMPILE Command 

The COMPILE command invokes the appropriate language processor to compile the 
specified source file. The TSX-Plus COMPILE command is the same as the RT-11 
COMPILE command except that it also recognizes programs with the extension 
"CBL" as COBOL source programs and calls the COBOL-Plus compiler. When 
compiling a COBOL program, the switches that are legal with the COBOL command 
may also be used with the COMPILE command. It is also possible to explicitly 
specify that the COBOL-Plus compiler is to be called by using the " /COBOL " 
switch with the COMPILE command. The default compiler for files with the 
extension "DBL" is DBL; this may be changed with the SET LANGUAGE command. 


The COPY Command 

The TSX-Plus COPY command has the same form and options as the RT-11 COPY 
command. 


The CREATE Command 

The TSX-Plus CREATE command has the same form and options as the RT-11 CREATE 
command. 
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The DATE Command 

The TSX-Plus DATE command has the same form and options as the RT-11 DATE 
command. Operator privilege is required to set the date. 


The DEASSIGN Command 

The TSX-Plus DEASSIGN command is equivalent to the RT-11 DEASSIGN command. It 
is used to dissociate a logical unit assignment. 


The DELETE Command 

The TSX-Plus DELETE command has the same form and options as the RT-11 DELETE 
command. 


The DETACH Command 

The DETACH command is used to initiate execution of a command file as a 
"detached” job, to abort a detached job or to check the status of a detached 
job. The system manager may restrict the use of this command. 

The form of the command used to start a detached job is: 

DETACH file 

where "file" is the name of a command file which is to be started as a detached 
job. If a free detached-job line is available, the system starts, the command 
file and prints a message indicating the detached job line number used. 
Detached-job lines must be declared when TSX-Plus is generated. The DETACH 
command itself and detached command files do not inherit any logical device 
assignments. If no device name is specified in the DETACH command, the command 
file is assumed to be on the system device (SY:). 

In the following example a command file named "CRUNCH" is started as a detached 
job. 


. DETACH CRUNCH 

Job started on line #5 

If the specified command file is not found, the start message will still 
appear, but the job is not actually started. Any error message would have been 
sent to the detached line, but is ignored since terminal output is not sent to 
detached jobs. With no input, the detached job then aborts. The result is 
that the detached job is not started and no warning appears. 

Terminal output for detached jobs is normally discarded since they are not 
attached to any terminal. However, it is possible to collect the terminal 
output from a detached job by sending it to a log file. This can be done by 
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using the SET LOG FILE=filnam command in the detached job command file. See 
the SET LOG command for more information on terminal output logging. 

The form of the DETACH command used to abort a detached job is: 

DETACH/KILL line-number 

where "line-number” is the number of the line assigned to the detached job. 

The form of the DETACH command used to check the status of a detached job line 
is: 

DETACH/CHECK line-number 

In response to this command, TSX-Plus will indicate whether a job is still 
executing on the line. 

See Chapter 4 for more information about detached jobs. 


The DIBQL Command 

The DIBOL command is used to compile a DIBOL source program. The default 
compiler for programs with the extension "DBL" is DBL. This may be changed 
with the SET LANGUAGE command. The TSX-Plus DIBOL command has the same form 
and options as the RT-11 DIBOL command, except that the options /BUFFERING, 
/LOG, /PAGE and /TABLES are not supported. Because of differences between 
compiler switch options, DIBOL switches are not supported for use with DBL. 


The DIFFERENCES Command 

The DIFFERENCES command is used to compare two files. The TSX-Plus DIFFERENCES 
command has the same form and options as the RT-11 DIFFERENCES command. 


The DIRECTORY Command 

The TSX-Plus DIRECTORY command has the same form and options as the RT-11 
DIRECTORY command. 
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The DISMOUNT Command 

The DISMOUNT command has three functions: 1) it tells TSX-Plus to stop 
directory caching on a particular device; 2) it tells the system to stop doing 
data caching on a device; 3) it dissociates a logical subset disk from its 
assigned file. The form of the DISMOUNT command is: 

DISMOUNT ddn 

where "ddn" is the real or logically assigned name of the device. 

If the device is a physical device or a logical name for a physical device, 
then the DISMOUNT command removes the current job's entry from the mount table 
for that device. If no other jobs have mounted the device, then directory and 
data caching for that device are stopped. Files on a physical device may still 
be accessed after it is DISMOUNTed, but access may be slower since the 
directory is no longer cached. Note however, that if a job accesses a device 
which it has not mounted, and another user INITIALIZES or SQUEEZES that device, 
then reads will probably return garbage and writes will probably corrupt other 
files. ALWAYS MOUNT ANY DIRECTORY STRUCTURED DEVICE WHICH YOU INTEND TO USE! 

The INITIALIZE and SQUEEZE operations cannot be performed on a device which is 

mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device 
which is mounted by other users, then they must first DISMOUNT that device. 
Remember that it is possible for a job which has not mounted a device to still 
access that device. After a device is INITIALIZEd or SQUEEZEd, then the 
directory and data caches are cleared for that device and if it is still 

mounted, then caching is resumed. Caching is not resumed if all jobs have 
DISMOUNTed a device until some job reMOUNTs that device. The following 
information message is printed if a device is dismounted and the device is 
still mounted by other users: 

?KMON-I-Device is still mounted by other users 

The SHOW MOUNTS command may be used to determine which jobs have devices 
mounted. 

In the case of logical subset disk assignments ("ddn” = LD0-LD7 or logical 
names assigned to them), the effect of the DISMOUNT command is to stop 

directory caching on the logical subset disk as described above and to remove 
the device from the logical subset disk tables. In this case, files on the 
logical subset disk are no longer accessible until the logical subset disk is 
re-mounted. This form of the command only affects the logical subset disks 
belonging to the user who issues the command. If another job has mounted the 
same logical subset disk, then the rules for physical devices with regard to 
INITIALIZE and SQUEEZE also apply to the logical subset disk. 
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The DISPLAY Command 


The DISPLAY command is used within a command file or user-defined command to 
cause a line of text to be displayed on the terminal when the command is 
executed. This is useful in command files that are not being listed to keep 
track of progress through the command file. The form of the DISPLAY command 
is: 


DISPLAY comments 

where "comments" can be any text string to be displayed on the terminal. See 
the section on user-defined commands in this chapter and Chapter 3 for more 
information on command files. 


The DUMP Command 
The TSX-Plus DUMP 


command. 


command has the same form and options as the RT-11 DUMP 


The EDIT Command 

The TSX-Plus EDIT command has the same form and options as the RT-11 EDIT 
command. 


The EXECUTE Command 

The TSX-Plus EXECUTE command has the same form and options as the RT-11 EXECUTE 
command. It also recognizes programs with the extension CBL as COBOL source 
programs and automatically invokes the COBOL—Plus compiler and linker. 
Switches appropriate when using the COBOL-Plus compiler and linker are also 
valid with EXECUTE. See also the COBOL, COMPILE, DIBOL, FORTRAN, LINK and 
MACRO commands. 


Vhe FORM Command 

The FORM command is used to specify the default form name for subsequent files 
sent to the spooler by the user. The form of the FORM command is: 

FORM name 

where "name" is the one to six character default form name to be used for all 
files sent to the spooler until another FORM command is issued. The initial 
default form name is "STD". A form may also be requested within a file sent to 
the spooler. See Chapter 5 for more information on spooled devices and forms. 
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In the following example a FORTRAN listing will be generated for printing on a 
form called "2-PART". 

. FORM 2-PART 
.COMPILE/LIST TEST.FOR 
.FORM STD 


The FORTRAN Command 

The TSX-Plus FORTRAN command has the same form and options as the RT-11 FORTRAN 
command. 


The HELP Command 

The TSX-Plus HELP command has the same form and options as the RT-11 HELP 
command. 


The INITIALIZE Command 

The TSX-Plus INITIALIZE command has the same form and options as the RT-11 
INITIALIZE command. However, the system device (booted device when TSX-Plus is 
started) may not be initialized when running TSX—Plus. If it is necessary to 
initialize the system device, it must be done under RT-11. The resulting error 
message is: 

?KMON-F-This operation not legal with SY (system) device 

A device cannot be initialized if any other user has MOUNTed the device. 
Attempts to INITIALIZE a device which is mounted by another user will result in 
the error message: 

7KM0N-F-Device is mounted by another user 

If the device is only mounted by the job which initializes it, then the 
directory and data caches are cleared after the operation and caching is 
resumed. The SHOW MOUNTS command may be used to determine which other users 
have mounted a device. However, remember that is still possible for a job 
which has not mounted a device to access that device. If such a job has a file 
open before you initialize, then severe problems can arise. Great circum¬ 
spection is necessary before initializing a device in a multi-user environment. 
Do not initialize rashly. As a defensive measure, always MOUNT any disk device 
which you plan to use. 
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If terminal output logging is being done (see the SET LOG command) and the log 
file is open on the device being initialized, then the log file is closed 
before the device is initialized and the following warning message appears: 

?KMON-W-Closing log file 


The KILL Command 

The KILL command is used to abort a timesharing job on another line. This has 
the effect of aborting the execution of the job and forcing the logoff of the 
line. Operator command privilege is required to use the KILL command. The 
form of this command is: 

KILL line-number 

where "line-number" is the number of the job to be killed. 


The KJOB Command 

The KJOB command is used to log off a timesharing line. It is equivalent to 
the OFF command. 


The LIBRARY Command 

The TSX-Plus LIBRARY command has the same form and options as the RT-11 LIBRARY 
command. It also can be used to build COBOL-Plus object program libraries; see 
the COBOL-Plus Reference Manual for further information. 


The LINK Command 

The TSX-Plus LINK command has the same form and options as the RT-11 LINK 
command. It also recognizes object files with the extension "CBJ" as COBOL- 
Plus object files and then invokes the COBOL-Plus link program (CBLINK). The 
COBOL-Plus linker may also be explicitly specified with the "/COBOL" switch. 
See the COBOL-Plus Reference Manual for further information. Switches which 
are unique to COBOL Plus - are: 

Switch 


/NOPAGE 

/NOSHARED 

/SHARED 

/SIZE 

/VM 

/XM 


Meaning 


Do not swap data segments. 

Do not use shared COBOL-Plus run-time library. 

Always use shared COBOL-Plus run-time library. 

Report the size of the largest data segment. 

Use VM for run-time and program segmentation. 

Load entire program and run-time into extended memory. 
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The MACRO Command 

The TSX-Plus MACRO command has the same form and options as the RT-11 MACRO 
command. 


The MAKE Command 

The MAKE command is used to create a new file with the TECO editor. It is 
equivalent to the RT-11 MAKE command. 


The MEMORY Command 

The MEMORY command is used to control the amount of memory available to a job. 
When a job initially "logs on" it receives a default memory allocation set by 
the system manager. The MEMORY command can be used to change the allocation 
for the job. The form of the MEMORY command is: 

MEMORY nn 

Where "nn" is the number of k-bytes (Kb, 1024. bytes) of memory to be allocated 
for the job. The maximum memory size that a job may use is set by the system 

manager, but never exceeds 64Kb. When a running program performs a .SETTOP EMT 

the top of memory address corresponds to the size last specified by a MEMORY 
command. Note that .SETTOP EMT's do not actually affect the amount of memory 
allocated to a job — only the MEMORY command and a TSX-Plus EMT described in 
Chapter 7 do that. 

Programs are only allowed to use more than 56Kb of memory if they are 
"virtual", meaning they do not directly access the RMON area, although they may 
access it indirectly by use of the .GVAL and .PVAL EMT^s. Programs may 

indicate that they are virtual by any of the following techniques: 

1. Set bit 10 (mask 2000) in the job status word (location 44) of the 

SAV file. See Appendix A for information about how the SETSIZ 

program can be used to do this. 

2. Use the /V LINK switch (/XM switch for the LINK keyboard command) 
which stores the RAD50 value for "VIR" in location 0 of the SAV file. 

3. Store a memory allocation size greater than 56Kb in location 56 of 
the SAV file. See Appendix A for information about how the SETSIZ 
program can do this. 

If none of these conditions is met the program is restricted to 56Kb even if a 
larger value is specified with the MEMORY command. 

See Chapter 8 and Appendix A for more information on memory usage and virtual 
images. 


- 37 - 













Keyboard Commands 

A program may dynamically control the amount of memory allocated for the job by 
use of the TSX-Plus EMT with function code 141 (described in Chapter 7). See 
also the description of the SETSIZ program in Appendix A for information about 
how the amount of memory to be allocated for a particular program can be stored 
in the SAV file for the program. 

If the MEMORY command is entered without specifying a size, the current and 
maximum memory allocation for the job is displayed. See also the description 
of the SHOW MEMORY command. 


The MONITOR Command 

The MONITOR command is used to cause TSX-Plus to begin a performance analysis. 
See Chapter 13 for complete information about the TSX-Plus performance analysis 
feature. The form of the MONITOR command is: 


MONITOR base-address,top-address[,cell-size]/switches 


where "base—address" is the lowest address in the program region being 
monitored, "top-address" is the highest address in the region, and "cell-size" 
is the number of bytes to group per histogram cell. The only valid switch is 
”/I" which causes I/O wait time to be included in the analysis. 


The MOUNT Command. 

The MOUNT command is used to: 1) begin directory caching on a file-structured 
device; 2) enable data caching on a device; and 3) associate a logical subset 
disk with a disk file. 

Directory caching is a technique that speeds up file lookups by keeping 
information about files in memory so that it is not necessary to access the 
directory on the device each time a file is opened. Data caching is a 
technique used to speed up disk reads by keeping memory resident copies of 
recently used file blocks. Both directory and data caching are enabled during 
TSX-Plus system generation and activated when a device is MOUNTed. The form of 
the MOUNT command to activate directory and data caching is. 


MOUNT ddn 

where "ddn” is a physical device name such as "DL1:". The effect of this type 
of MOUNT command is to tell TSX-Plus that it should begin directory and data 
caching for the device being mounted. The system device is automatically 
MOUNTed for each user. If caching is not wanted, then no MOUNT should be 
performed, or the DISMOUNT command should be used to halt caching on a 
previously mounted disk. 
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The INITIALIZE and SQUEEZE operations cannot be performed on a device which is 
mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device 
which is mounted by other users, then they must first DISMOUNT that device. 
Remember that it is possible for a job which has not mounted a device to still 
access that device. 

Once a MOUNT command is issued, caching is enabled for all users who access 
files on the device (including users who have not MOUNTed the device). The 
system maintains a table of all users who have mounted each device. See also 
the DISMOUNT and SHOW MOUNTS commands. 

Warning: If directory caching is enabled for a device, it is crucially 
important that the DISMOUNT command be used to dismount the device before a 
disk is replaced on the same drive. If a new disk pack is inserted in the 
drive without issuing the DISMOUNT command, TSX-Plus would try to access files 
on the new pack according to the locations stored in the directory cache for 
the old pack. 

Directory caching causes a dramatic improvement in the speed of file "lookups" 
but does not speed up file "enters", "deletes" or "renames". This is because 
TSX-Plus always updates the directory on the device when it is altered. The 
maximum number of devices whose directories may be cached and the number of 
file entries that are kept in the directory cache are specified when TSX-Plus 
is generated. 

The second form of the MOUNT command is used to associate a logical subset disk 
with a disk file. The form of the command is: 

MOUNT[/[NO]WRITE] LDn filnam [logical-name] 

where "LDn" is the logical subset disk, and n is in the range 0-7, "filnam" is 
the name of a disk file containing the subset files, and "logical-name" is an 
optional logical name to be assigned to the logical subset disk. The [NOJWRITE 
option controls access to the logical subset disk. WRITE allows full access, 
whereas NOWRITE allows read-only access. WRITE access is allowed by default 
unless the NOWRITE option is used. The default extension for the disk file to 
be associated with a logical subset disk is "DSK". File protection is 
automatically set on the file specified to be a logical subset disk. When a 
logical subset disk is mounted, directory and data caching are also begun for 
it. 

Each user may mount up to 8 logical subset disks at any time. The association 
between a logical subset disk (LD0-LD7) and a file is "local" to each user. 
For example, one user may associate LD2 with file DL1 :MYDISK.DSK while another 
user associates LD2 with file DL1:YORDSK.DSK. 

Logical subset disks may be "nested", allowing one or more subsets to be 
defined within other subsets. However, if this is done, the MOUNT commands 
must be executed sequentially from outer-most to inner-most logical subset disk 
and the unit numbers must be assigned sequentially from LDO to LD7. 
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Example: 

.MOUNT LDO MANUAL MAN 

•CREATE LDO:SUB.DSK/SlLOCATE:100. 

•MOUNT/WRITE LD2 MAN:SUB 
• INIT/NOQ LD2: 

Other commands which refer to logical subset disks are: DISMOUNT, SET LDn 
{CLEAN|WRITE|NOWRITE} and SHOW SUBSETS. The ACCESS command may also be used 
with logical subset disks in start-up command files. The restrictions on 
INITIALIZE and SQUEEZE operations also apply when another user has mounted the 
same logical subset disk. 

Logical subset disk support is integral to the file management functions of 
TSX-Plus, and does not require the H LD" pseudo-device handler. Consequently, 
it is independent of the version of RT-11 supporting TSX-Plus. See Appendix G 
for more information on the use of logical subset disks. 


The MUNG Command 

The MUNG command is used to start a file of TECO commands. The MUNG command is 
equivalent to the RT-11 MUNG command. 


The OFF Command 

The OFF command is used to log off a time-sharing line, and to release a 
virtual line (see the discussion of virtual lines in Chapter 4). The accumu¬ 
lated connect time and CPU time used during the session are printed during the 
logoff processing. The BYE and KJOB commands are synonyms for the OFF command. 
TSX-Plus automatically logs off dial-up lines if the telephone connection is 
broken. A special log-off command file may also be designated to execute 
whenever a job logs off; see the TSX-Plus System Manager's Guide for more 
information. 

Example: 

.OFF 


Connect time=01:43:00 CPU=00:12:03 


The OPERATOR Command 

The OPERATOR command is used to send a message to the operator's console. The 
OPERATOR command works like the SEND command, but it is not necessary to know 
the line number of the operator s terminal. The form of the OPERATOR command 
is: 
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OPERATOR message 

For example, to send a disk mount message to the operator: 
.OPERATOR PLEASE MOUNT PAYROLL MASTER DISK ON RK1 


The PAUSE Command 

The PAUSE command is used within command files (see Chapter 3) to temporarily 
suspend processing of the file. The form of the PAUSE command is: 

PAUSE comments 

where "comments" may be any string of characters. When a PAUSE command is 
encountered within a command file, the PAUSE command is printed on the terminal 
followed by >>”. Execution of the command file is suspended until carriage 
return is pressed. This gives the operator an opportunity to perform manual 
operations such as mounting disks or tapes. 


The PRINT Command 

The TSX-Plus PRINT command has the same form and options as the RT-11 PRINT 
command. 


The PROTECT Command 

The TSX-Plus PROTECT command has the same form and options as the RT-11 PROTECT 
command. 


The R Command 

The "R" command is used to start a program. The form of the command is: 
R[/switch] filnam [input-data] 

If no device name is specified with the program name, TSX-Plus attempts to find 
the specified program on "SY: M . The amount of memory available to a program 
can be controlled with the MEMORY command, or size information can be included 
in its disk image. See the description of the SETSIZ program in Appendix A for 
more information about how the amount of memory allocated for a program may be 
controlled. See also Chapter 8 for more information on the operating environ¬ 
ment for programs under TSX-Plus. 

A line of input may be passed to a program by specifying it as part of the "R" 
command following the program name. If this is done the program will receive 
the text string as its first line of input and will receive control-C as its 
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second line of input. (See example 2 below.) Note that only programs which 
accept input with the .GTLIN, .CSISPC, and .CSIGEN requests can accept input in 
this manner. Single character input (.TTYIN) does not normally accept data 
from a command line; however, the program can be invoked with a command file 
and accept all terminal input from the command file — see the section on 
command file control characters in Chapter 3. Note also that text passed on 
the command line will be reorganized ir it contains multiple words separated by 
spaces. The first word will be placed as the input to a CSI command string and 
the remainder of the line will be placed on the output side of the equal sign. 
(See example 7 below.) 

The valid switches for the R (and RUN) command are: 

/DEBUG — Run program under control of debugger 

/HIGH — Run program in high efficiency TTY mode 

/LOCK — Lock program to line 

/NONINTERACTIVE — Run program in non-interactive mode 
/SINGLECHAR — Run program with single-character activation 

All switches can be abbreviated to a single character. 

The /DEBUG switch causes the program being started to execute under control of 
the TSODT debugging program. Before loading the program, a relocatable copy of 
the TSODT program ("SY:TSODT.REL") is loaded into the upper-most portion of the 
user's available memory space (reducing the memory space available to the 
running program by about 4Kb). The program being started is then loaded into 
the memory space below TSODT and control is passed to TSODT. TSODT responds by 
printing a greeting message and waiting for a command from the terminal. At 
this point register 0 ("$0") contains the address of the starting point of the 
program. TSODT may be used to display or examine locations or set breakpoints 
in the program. The program is started with the TSODT "xxxxxx;G" command 
(where "xxxxxx" is the starting address of the program). The /DEBUG switch 
allows programs run under TSX-Plus to be debugged without special linking with 
a debugging program. Because of the mapping for TSKMON while TSODT is being 
loaded, programs larger than 28Kb must be linked with TSODT for debugging 
rather than use the /DEBUG switch. Commands and functions of TSODT are 
equivalent to those of ODT provided with RT-11. 

The /HIGH switch automatically enables the program to use high efficiency 
terminal I/O. This disables much of the character testing done during terminal 
operations and can increase terminal throughput. See the description of the 
"R" program controlled terminal option in Chapter 6 for more information on 
high efficiency terminal mode. 

The /LOCK switch causes the program that is being started to be "locked" to the 
time-sharing line so that the line is automatically logged off when the program 
exits. If the "R/LOCK" command occurs within a command file the command file 
is terminated as the program is started and any additional information in the 
command file is ignored. The most frequent use of this feature is in start-up 
command files where a line is to be restricted to executing a particular 
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program. If a locked program chains to another program, the program that was 
chained to then becomes the locked program. See example 4 below. 

The /NONINTERACTIVE switch prevents a program from receiving the priority boost 
normally given to jobs on the completion of terminal input. This should be 
used with programs which do heavy terminal I/O but which are not really 
interactive jobs, such as file transfer programs. A program run with this 
switch will execute at a lower priority and will not interfere with interactive 
jobs. The effect of this switch is cleared when a program exits to KMON, but 
the switch remains in effect if the program chains to another program. 

The /SINGLECHAR switch causes a program to execute in "single character 

activation” mode. (See the discussion of activation characters in Chapter 6.) 
Normally when programs are run under TSX-Plus they do not receive terminal 
input until an "activation” character such as carriage-return has been entered. 
This is true even if the program sets bit 12 in the Job Status Word. Also, 

TSX-Plus does not normally allow a program to test for terminal input without 

stalling on the .TTYIN EMT. However, the /SINGLECHAR switch causes TSX-Plus to 
honor bits 6 and 12 of the Job Status Word, allowing the program to activate on 
each character and test for terminal input without stalling. A program can 
also cause TSX-Plus to honor JSW bits 6 and 12 by using the "U" and "S" 

terminal control commands (see Chapter 6). The example program "STEALS" in the 
section on requesting exclusive system control in Chapter 11 uses single 
character activation in this way. KED and K52 are automatically run in single 
character activation mode. 

Examples: 

1. Run the program named "DUMP" on device "SY:". 

.R DUMP 

2. Run the program named "PIP" on "SY:" and pass to it the 
input line "A.TMP=B.TMP. 

.PIP A.TMP=B.TMP 


3. Run the program named "SAMPLE" on "RK2:". 

.R RK2:SAMPLE 

4. Start the execution of BASIC and force logoff on exit. 
. R/LOCK BASIC 

5. Start a program named PLANE and allow it to 
use single character activation mode. 

.R/SINGLE PLANE 


-43- 



















Keyboard Commands 


6. Start a program named TRIAL in debug mode so that 
it will be run under TSODT. 

•R/DEBUG TRIAL 
*TSX-0DT-V4* 

* 

7. Start the program SYiGETLIN and pass it some input text. 
.R GETLIN INPUT OUTPUT 

The program GETLIN will receive the following text: 
OUTPUT=INPUT 


The RENAME Command 

The TSX-Plus RENAME command has the same form and options as the RT-11 RENAME 
command. 


The RESET Command 

The RESET command is used to reset the system usage statistics that are 
displayed with the SYSTAT command. Data caching statistics are also reset by 
the RESET command. This is useful when you want to monitor system performance 
during a particular part of the day. Operator command privilege is required to 
use the RESET command. The TSX-Plus RESET command is NOT equivalent to the 
RT-11 RESET command. 


The RUN Command 

The RUN command is equivalent to the "R" command except that the default device 
is "DK:" instead of "SY:". See the description of the ”R M command for 
information about available switches. 


The SEND Command 

The SEND command is used to send messages between time-sharing terminals. The 
form of the command is: 

SEND[,line#] message 

where "line#" is the number of the line to which the message is to be sent. If 
no line number is specified, the message is broadcast to all logged-on lines. 
Jobs may inhibit the reception of messages while executing programs by using 
the SET TT GAG command. 


'W 
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Examples: 


1. Send a message to all logged—on users: 

. SEND Bob, Call me when you get a. chance. 

2. Send a message to line number 2: 

. SEND,2 Will you be on tonight? 

When a SEND message is printed at a terminal, the message is preceded by the 
number of the line that originated the message and the user name currently 
associated with that line. For example, a message from line 1 might be printed 
as follows: 

01 (SYSMGR) — Bob, Call me when you get a chance. 

Keep in mind that several characters are used to identify the sending line and 
user, with the result that a long message may be truncated. 


The SET Command 

The SET command is used to set various options controlling system operation. 
The general form of the SET command is: 

SET device option 

As with RT-11, the TSX-Plus SET command is used to specify options .for devices 
such as line-printers and card-readers as well as setting certain system 
parameters such as terminal control characteristics. When used to set device 
options, the SET command has the same form as under RT-11 and may set the same 
options (they are specified in the handler). The SET command causes the copy 
of the device handler on the disk to be altered so that the effect of the 
command becomes "permanent" (until another SET changes the parameter back). 
The SET command also attempts to make the change to the copy of the handler 
that is in memory with TSX-plus. If the handler is idle when the SET is done, 
the change will be made; otherwise, a warning message: 

7KM0N-F-Handler active — Can't update running copy 

will be printed and the running copy of the handler is not altered. When a SET 
is done to a device handler, blocks 0 and 1 of the handler are read from the 
disk, the SET option is applied and then block 1 is written back to the disk 
and moved over the copy of block 1 that is in memory. If the vector of a 
device is changed with the SET dd VECTOR=nnn command, TSX-Plus must be 
restarted to function correctly. Operator command privilege is required to set 
an option in a device handler. See the RT-11 System User's Guide for device 
handler SET options. 
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SET CACHE 

The SET CACHE command is used to alter the number of blocks which may be held 
in the generalized data cache. This command does not alter the amount of 
memory reserved for the data cache, but only controls the number of blocks 
within the limits allowed by the CACHE parameter selected during system 
generation. This command is used by the system manager to determine the effect 
of varying cache sizes on system performance. Operator privilege is necessary 
to use this command. The form of this command is: 

SET CACHE blocks 

where ’’blocks" may range from 0 to the number of blocks reserved by the CACHE 
parameter during system generation. 


SET CCL 

There are two types of system commands, low level commands such as RUN, SET, 
ASSIGN and high level commands such as EXECUTE, COPY, DELETE, and DIRECTORY. 
Low level commands are executed directly by TSX-Plus. High level commands are 
translated into the appropriate low level commands before execution. The set 
of high level commands is known as the Concise Command Language (CCL). The 
"SET CCL" command can be used to observe the low level commands that are 
produced by translating CCL commands. The form of this command is: 

SET CCL [NOjTEST 

When TSX-Plus is in CCL TEST mode, it will display at the terminal the low 
level commands that are generated by a CCL command, but not execute them. The 
"SET CCL NOTEST" command turns this mode off and TSX-Plus goes back to 
executing CCL commands. Test mode is very useful if you are having trouble 
getting some complex CCL command to work and want to examine the low level 
commands that are being generated. 

Example: 


.SET CCL TEST 

.DIR/OUTPUT:DIR.DAT/OCTAL/BLOCKS DLl: 
R DIR 

DK:DIR.DAT=DL1:*.*/0/B 
~C 

.SET CCL NOTEST 
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SET CORTIM 

The SET CORTIM command is used to adjust the value of the CORTIM system control 
parameter. This parameter controls the minimum memory residency time for jobs 
just swapped into memory. See the TSX-Plus System Managers Guide for further 
information about the CORTIM parameter. The form of this command is: 

SET CORTIM value 

where value is the time value specified in 0.1 second units. The current 
value of the CORTIM parameter may be determined with the SHOW CORTIM command. 
Operator command privilege is required to use this command. 


SET EDIT 

The SET EDIT command is used to select which edit program will be invoked when 
the system EDIT command is used. The form of this command is: 

SET EDIT option 

where ‘option" may be EDIT, TECO, KED or K52. The options KED and K52 are 
actually synonymous; the KED editor is used if the terminal type has been 
specified to be a VT100 and the K52 editor is used if the terminal type has 
been specified to be a VT52. The terminal must be SET TT LC in order to use 
KED or K52. 


SET EMT 

The SET EMT command is used to control tracing of EMT calls during the 
execution of a user program. The form of the command is: 

SET EMT [NO]TRACE 

When SET EMT TRACE is specified, a line of information about the EMT call is 
displayed at the terminal each time an EMT is executed. The .TTYIN, .TTYOUT 
and .PRINT EMTs, however, are not included in EMT traces. EMT tracing is 
disabled with the SET EMT NOTRACE command. Each line of information which is 
displayed during EMT tracing contains: the virtual address of the EMT call, 
the EMT code, function code, channel number (or sub-function code), and the 
first 5 words in the EMT argument block. Only the first two items are defined 
for all EMTs. The other items are defined only if used for the EMT currently 
being traced. As an example of EMT tracing, the LNTT program which displays 
the current line number and terminal type (see Chapter 7) was traced as 
follows: 
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•SET EMT TRACE 
•RUN LNTT 


001004 

374 

004 

000 

000000 

000000 

000610 

000000 

000000 

001012 

375 

110 

000 

057400 

001252 

001262 

001270 

001277 

001026 

TSX-Plus 

Terminal 

374 

line 

type 

005 000 

number: 

057400 

2 

001252 

001262 

001270 

001277 

001060 

VT-100 

375 

137 

000 

001252 

001262 

001270 

001277 

001311 

001072 

.SET EMT 

350 016 

NOTRACE 

010 

001270 

001262 

001270 

001277 

001311 


Note that the .PRINT calls are not traced, since .TTYIN, .TTYOUT and .PRINT 
EMTs are never traced. Appendix D contains a list of both RT-11 compatible and 
^ TSX-Plus specific EMTs. 


SET ERROR 

The SET ERROR command is used to specify the level of error which will abort 
command file execution. The form of this command is: 

SET ERROR option 

where "option" may be FATAL, SEVERE, ERROR, WARNING or NONE. Command files 
being executed under the IND program are not normally aborted if errors occur 
during execution; the SET IND ABORT command can be used to cause IND command 
files to abort according to the same rules as for normal command files. The 
TSX-Plus SET ERROR command functions in the same fashion as the RT-11 SET ERROR 
command. 


SET HIPRCT 


The SET HIPRCT command is used to set the value of the HIPRCT system control 
parameter. See the TSX-Plus System Manager's Guide for more information on the 
effect ot this parameter. The form of this command is: 


SET HIPRCT value 

where "value" sets the non-interactive job I/O counter. Operator privilege is 
necessary to use this command. The HIPRCT parameter may be referenced by the 
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for 
more information on job scheduling and performance optimization. 
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SET IND 

The SET IND [NO]ABORT command is used to control the execution of command files 
under the control of the IND program when there is an error. Normally, command 
files under the control of IND are not aborted when an error occurs, regardless 
of the current SET ERROR level. However, if the SET IND ABORT command is 
issued, then command files under the control of the IND program will abort 
under the same conditions as would normal command files. The SET IND NOABORT 
command restores the default abort processing under IND control (no abort). 


SET INTIOC 

The SET INTIOC command is used to set the value of the INTIOC system control 
parameter. See the TSX-Plus System Manager's Guide for more information on the 
effect of this parameter. The form of this command is: 

SET INTIOC value 

where "value" is the interactive job I/O counter. Operator privilege is 
necessary to use this command. The INTIOC parameter may be referenced by the 
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for 
more information on job scheduling and performance optimization. 


SET 10 

The SET 10 [NOJABORT command is used to select the method of handling I/O abort 
requests. If the SET 10 ABORT command is issued, then an I/O abort request 
will call device handler abort entry points. If the SET 10 NOABORT command is 
issued, then I/O abort requests will proceed through I/O rundown; that is, all 
pending I/O will complete before the job is aborted. The initial setting of 
this parameter is selected during TSX-Plus system generation. Operator 
privilege is required to use this command. The method selected affects all 
lines, not just the line from which the command is issued. 


SET KMON 

The SET KMON command is used to direct the processing of commands from the 
keyboard and from command files. The form of this command is: 

SET KMON option 

where the valid options are: [NO]IND, UCI[=filnam] and SYSTEM. The chain of 
events in command processing by TSX—Plus is described at the beginning of this 
chapter. 

The processing of indirect command files may either be controlled by TSX-Plus 
or by the IND utility provided with RT-11. To cause command files to be 
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processed by IND, use the command: SET KMON IND. To return to the normal mode 
of TSX-Plus command file processing: SET KMON NOIND. Note that command files 
which result in errors are not normally aborted, regardless of the SET ERROR 
level, when executed under control of IND. The SET IND [NO]ABORT command can 
used to control error abort of IND command files. Command files may be forced 
to the normal TSX-Plus mode of execution regardless of whether KMON is set IND 
or NOIND by calling them as: 

$@filnam 

Conversely, command files may be forced to execute under the IND utility 
regardless of whether KMON is set IND or NOIND by calling them as: 

IND filnam 

See Chapter 3 for more information on command file processing. 

The other function of the SET KMON command is to control the user command 
interface. It is possible for user written programs to accept and pre-process 
keyboard commands before the TSKMON program. Command control is local to each 
user. That is, each job may select its own command processing method. The 
User Command Interface may be enabled by the command: 

SET KMON UCI[=filnam] 

When UCI is in effect, then each time TSKMON is ready to accept a command it 
passes control to the current UCI program. If the optional "=filnam" has been 
omitted, then TSKMON passes command acquisition control to the program 
SY:UKMON.SAV. If a file has been specified, then TSKMON passes control to that 
program. It is the responsibility of the user-written command interface 
program to prompt for and accept command input lines. Commands may be further 
passed on to TSKMON through the chain-data area by doing a special chain exit. 

Command processing control is returned to TSKMON by the command: 

SET KMON SYSTEM 

See the example program in the section on the User Command Interface earlier in 
this chapter for more information. 


SET LANGUAGE 

The SET LANGUAGE command is used to select DBL or DIBOL as the default compiler 
for programs with the extension DBL. This also affects the COMPILE and EXECUTE 
commands. The form of the command is: 

SET LANGUAGE option 

where "option” is DBL or DIBOL. The default setting of this parameter is DBL. 
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SET LD 

The SET LD command is used to control writing to a logical subset disk and to 
verify logical subset disk assignments. The form of the command is: 

SET LDn option 

where "LDn" is in the range of LDO to LD7, and ’’option" may be CLEAN, WRITE or 
NOWRITE. To prevent writing to a logical subset disk, SET LDn NOWRITE. To 
allow writing to a logical subset disk, SET LDn WRITE. WRITE/NOWRITE control 
is also an option of the MOUNT command. SET LDn CLEAN is used to verify and 
correct logical subset disk assignments. An implicit SET LDn CLEAN is done by 
TSX-Plus whenever the DUP utility program is run (e.g. INIT and SQUEEZE 
operations). See the MOUNT command for further information on the use of 
logical subset disks. 


SET LOG 

It is possible to copy terminal output to a log file. When terminal logging is 
enabled, all output directed to the terminal is also written to the log file. 
The only exception to this is high-efficiency terminal output which is not 
logged. To initiate terminal logging issue the following command: 

SET LOG FILE=name 

where "name" is the file specification for the log file. The default extension 
is ".LOG". For example, the following command would copy terminal output to a 
file named "DK:RUNLST.LOG": 

SET LOG FILE=RUNLST 

The following command causes terminal output to be copied to the line printer: 
SET LOG FILE=LP: 

Logging of terminal output may be stopped and the log file closed by the 
command: 

SET LOG CLOSE 

The log file is automatically closed when another log file is opened or the job 
logs off. The log file is also automatically closed if the device containing 
the log file is initialized or squeezed; the following warning message appears: 

?KMON-W-Closing log file 
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It may be desirable to suspend and resume terminal output logging during some 
operations without closing and reopening another log file. To temporarily 
suspend terminal logging, issue the command: 

SET LOG NOWRITE 

To resume terminal logging, issue the command: 

SET LOG WRITE 

It may be desirable at some times to reset the terminal log file. To clear the 
contents of the log file without closing and deleting the file, issue the 
command: 

SET LOG CLEAN 

Terminal logging is especially useful with detached jobs. Terminal output to 
detached jobs is normally discarded since the job is not attached to any 
terminal. However, when terminal logging is enabled for a detached job, then 
the terminal output may be directed to a file or to a printer. 


SET LOGOFF 

The SET LOGOFF command is used to associate a "log—off" command file with a 
job. This command is only valid within start-up command files. The form of 
this command is: 

SET LOGOFF FILE=name 

where name is the file specification of a command file to be executed when 
the job logs off. Log-off command files, like start-up command files, cannot 
be aborted by control-C. See the TSX-Plus System Manager's Guide for further 
information about log-off command files. 


SET MAXPRIORITY 

The SET MAXPRIORITY command may be used to reduce the maximum priority allowed 
to a job. When placed in a start-up command file, this command restricts the 
maximum available priority for that job. This permits restriction of priority 
on lines which do not use the LOGON facility. The form of this command is: 

SET MAXPRIORITY value 

where "value*’ is in the range of 0 to 127. If the current maximum job priority 
is less than 127, then the current maximum priority is the upper limit for the 
valid range of "value". See the TSX-Plus System Manager s Guide for further 
information about restricting job priority. 
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SET NUMDC 

The SET NUMDC command is used to control the number of buffers used for data 
caching. The form of this command is 

SET NUMDC value 

where "value” is the number of buffers to use. The initial value of the NUMDC 
parameter is specified when the system is generated. The SET NUMDC command may 
be used to restrict the number of data cache buffers actually used to a value 
less than the number of buffers specified when the system was generated, but 
may not exceed that value. The SET NUMDC command does not alter the memory 
space allocated for cache buffers, it merely controls the number of buffers 
actually used. Operator command privilege is required to use this command. 

The primary use of the SET NUMDC command is to determine the optimum number of 
data cache buffers to include in a system. To do this, the system can be 
generated with a large number of data cache buffers and the SET NUMDC command 
can be used to determine the minimum number which are actually needed to 
provide effective performance. When using this procedure, all files that are 
being cached should be closed before the SET NUMDC command is issued. See 
Chapter 9 for a discussion of shared-file data caching. 


SET PRIORITY 

The SET PRIORITY command is used to set the execution priority for a time¬ 
sharing job. The form of the command is: 

SET PRIORITY value 

where "value" may range from 0 to 127. The default priority assigned to a job 
when not otherwise specified or restricted is 50. The maximum priority allowed 
to a job may be restricted through the logon mechanism or the SET MAXPRIORITY 
command. The SHOW PRIORITY command can be used to display the current job 
priority and the maximum authorized priority. The SYSTAT command also displays 
current job priorities. 

Job priorities may also be assigned from within an executing program with an 
EMT. See Chapter 7 for more information on setting job priority from within a 
program. 

When a job is disassociated from the terminal by switching to a different 
virtual line the job is reduced in priority by an amount determined during 
system generation (the PRIVIR parameter). 

The job priority value is used by the scheduler to determine which job has 
precedence and should be run next. The priority value is only used when there 
is more than one job in the same executable state queue. See Appendix H for 
more information about job execution priorities. See the TSX—Plus System 
Manager's Guide for more information on job scheduling. 
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SET PROMPT 

The SET PROMPT command is used to change the keyboard monitor prompt character. 
The default character is a period The form of the command is: 


SET PROMPT "string" 

where "string" is a quoted string containing from 1 to 8 characters. The 
quoted string will subsequently be used as the keyboard monitor prompt string. 
For example, in order to set the monitor prompt to a dollar sign followed by a 
space (the standard VMS prompt string), use the following command: 

SET PROMPT "$ " 

To restore the standard RT-11 prompt string, issue the command: 

SET PROMPT 


SET QUANxx 

Th7 SET QUANxx command is used to set the value of the system time-slice 
control parameters (QUANO, QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3). See the 
TSX-Plus System Manager's Guide for information about the effect of the these 
parameters. The form of this command is: 

SET QUANxx value 

where "value" is the time value specified in 0.1 second units. Operator 
command privilege is required to use this command. The value selected takes 
effect for all jobs on the system, not just the job issuing the command. These 
parameters may be referenced by the SET SIGNAL and SHOW commands. See the 
TSX-Plus System Manager's Guide for more information on job scheduling and 
performance optimization. 


SET SIGNAL ^ . 

The SET SIGNAL command is used as an aid to system performance tuning. 

form of the SET SIGNAL command is: 


The 


SET SIGNAL [NO]parameter 

where "parameter" may be one of the system scheduling parameters: HIPRCT, 
INTIOC, QUANO, QUANl, QUAN1A, QUAN1B, QUAN1C, QUAN2, or QUAN3. Only one 
parameter may be selected by each SET SIGNAL command, although with multiple 
SET SIGNAL commands more than one parameter may be selected for signaling at 
once. Signaling may be disabled for any individual parameter by prefacing the 
parameter with "NO". Signaling may be halted for all parameters with the 
command SET SIGNAL OFF. 
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When signaling has been enabled for a system tuning parameter, the bell will be 
rung at the terminal of the job for which signaling has been selected each time 
the job changes state because it exceeds the value of the selected parameter. 
The SET SIGNAL command functions on a line-by-line basis and only affects the 
line from which the command is issued. 

The signaling feature is intended as an aid to the system manager in deter¬ 
mining appropriate values of the system tuning parameters for a given job. See 
the TSX-Plus System Manager's Guide for more information on use of the 
signaling feature. 


SET SL 

The SET SL command is used to control the ability to edit keyboard input lines. 
The TSX-Plus SL facility is generally compatible with that provided with the 
RT-11 "SL” editor. It allows editing of the current input line or field and 
recall of the previous input line or field. See the section on the single line 
editor in Chapter 1 for information on the use of the single line editor. The 
form of this SET command is: 

SET SL option 

where the options are described below. 

Option Meaning 


ASK This command is ignored. The terminal type is determined from the 

current TSX-Plus terminal type. 

K52 This command enables "KED"-like extensions to the single line editor. 

Note that the numeric keypad is set to application mode. 

KED This command enables "KED"-like extensions to the single line editor. 

Note that the numeric keypad is set to application mode. 

KEX This command enables , KED"-like extensions to the single line editor. 

Note that the numeric keypad is set to application mode. 

[NO]LEARN This command is ignored. The single line editor LEARN mode is not 

implemented. 

[NO]LET This command is ignored. The LET utility may not be used with the 

single line editor. 

OFF This command turns off the single line editor. 

ON This command turns on the single line editor. Note that the job is 

in single-character activation mode. 
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RT11 This command disables the "KED"-like extensions to the single line 

editor. 

SYSGEN This command is ignored. The single line editor is implemented as a 
TSX-Plus system overlay region and does not require the SL pseudo¬ 
device handler. 

[NO]TTYIN This command either enables (TTYIN) or disables (NOTTYIN) editing of 
keyboard input being accepted via the .TTYIN EMT from within 
programs. 

VT52 This command is equivalent to SET TT VT52. Ensure that your terminal 

responds to VT52 type control sequences before issuing this command. 

VT62 This command is equivalent to SET TT VT52. Ensure that your terminal 

responds to VT52 type control sequences before issuing this command. 

VT100 This command is equivalent to SET TT VT100. Ensure that your 

terminal responds to VT100 type control sequences before issuing this 
command. 

VT101 This command is equivalent to SET TT VT100. Ensure that your 

terminal responds to VT100 type control sequences before issuing this 
command. 

VT102 This command is equivalent to SET TT VT100. Ensure that your 

terminal responds to VT100 type control sequences before issuing this 
command. 

WIDTH=n This command is ignored. The maximum input line width that can be 
used with the single line editor, either as a command line or in a 
program data field, is 80 characters. 


SET TERMINAL 

The SET TERMINAL command is used to set various terminal parameters. It is 
equivalent to the SET TT command. 


SET TT 

The form of this SET command is: 

SET TT [NO]option 

to turn an option off and on. Some options require a numeric parameter, in 
which case they are specified as: 

SET TT option=value 
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Option 

Meaning 

ADM 3A 

Tells TSX-Plus that the terminal being used is a Lear Siegler ADM3A 
and also has the effect of SET TT SCOPE, NOTAB, NOFORM. 


DECWRITER Equivalent to the LA36 option. 

[NOJDEFER TSX-Plus offers two modes of character echoing — "deferred" and 



immediate (NODEFER). If the user only types input to programs 
while they are waiting for input, the two modes function identically. 
However, if the user types input before the program finishes 
processing the previous line of input, the two modes are different. 
In immediate (NODEFER) mode the input characters are echoed immedi¬ 
ately and may be printed even before the program prints the response 
to the previous line. In deferred echo mode, the characters that are 
typed ahead are accepted and held for the program, but are not echoed 
to the terminal until the program is ready to accept them. Under 
standard RT-11, EDIT, BASIC, and DIBOL programs run in deferred mode. 
Most other programs use immediate echoing. Deferred echoing is the 
preferred mode under TSX-Plus. See Chapter 6 for information about 
how a program can control deferred echo mode. 

DIABLO 

Has the effect of SET TT NOSCOPE, FORM, NOTAB, PAGE. The QUME type 
is equivalent. When doing plotting or printing with proportional 
spacing, SET TT TAB. 

[NO]ECHO 

Controls echoing of characters to the terminal. See Chapter 6 for 
information about how a program can control character echoing. 

[NO]FORM 

Controls conversion of form feed (FF) characters to line feeds. FORM 
should be set with terminals whose hardware can respond to form feed 
characters. NOFORM should be used for terminals whose hardware 
cannot handle form feed characters. When NOFORM is set, form feed 
characters are replaced by eight line feed characters. 


[NOJFORMO The FORMO option causes TSX-Plus to first issue a form-feed when a 
write is done to the terminal with a block number of zero. This is 


[NO]GAG 

convenient when producing multiple program listings to cause each 
listing to begin at the top of a new page. The NOFORMO option 
disables special handling of block zero writes. 

The GAG option inhibits messages sent from another line from being 
displayed at the terminal. This is only in effect when the job is 
executing a program. Messages are not inhibited while in the 
keyboard monitor. The NOGAG option allows messages to be displayed 
at any time. The GAG option is useful for preventing messages from 
interrupting jobs on hardcopy terminals, such as printers or 
plotters, where a message could spoil the format. This command only 
affects messages sent either with the SEND command or the EMT which 
sends a message to another job. This does not apply to message 
communication channels. 
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HAZELTINE Tells TSX-Plus that the terminal being used is a Hazeltine brand 
terminal and also has the effect of SET TT SCOPE, NOTAB, NOFORM. 

LA36 Tells TSX-Plus that the terminal being used is an LA36 and also has 

the effect of SET TT NOSCOPE, NOTAB, NOFORM. 

LA120 Tells TSX-Plus that the terminal being used is an LA120 and also has 

the effect of SET TT PAGE, TAB, FORM, NOSCOPE. 

[NO]LC Allows lower case characters to be passed to a program. If LC is set 
and bit 14 of the job status word is set to 1, input of lower case 
characters from the terminal will be passed to the running program. 
If the terminal is set NOLC o_r the Job Status Word bit 14 is clear, 
lower case characters are translated to upper case. See Chapter 6 
for information about how a program can control lower-case character 
conversion. Note that in order to use the keypad editors KED and K52 
the terminal must be SET TT LC. 

[NOJPAGE PAGE allows CTRL-S and CTRL-Q characters to suspend and restart 
terminal output. When the terminal is set NOPAGE, CTRL-S and CTRL-Q 
have no special effect and are passed directly to the running 
program. 

[NOJQUIET Setting the terminal QUIET suppresses the listing of command files as 
they are executed. When the terminal is set NOQUIET, command file 
lines are listed as they are executed. See Chapter 3 for additional 
information on controlling command file listing. 

QUME Equivalent to the DIABLO type. Has the effect of SET TT NOSCOPE, 

FORM, NOTAB, PAGE. When doing plotting or printing with proportional 
spacing, SET TT TAB. 

[NO]SCOPE Tells TSX-Plus whether the terminal is a CRT device. Setting SCOPE 
causes the DELETE key to echo as a backspace-space-backspace 
sequence, erasing the previously typed character. See Chapter 6 for 
information about how a program can specify an alternate "rubout 
filler*' character that will be used to overwrite characters being 
erased when DELETE is typed. When the terminal is set NOSCOPE, the 
DELETE key causes preceding characters to be echoed in reverse order 
as they are removed from the input buffer, and CTRL-U echoes carriage 
return, line feed. CTRL-R can be used to check the current contents 
of the input buffer when doing rubout editing. See Chapter N1 for 
information on other special control characters. \ 

[NO]SINGL Controls automatic single character activation for programs. If', the 
SET TT SINGLE command has been issued, then programs may control 
single character activation on terminal input by toggling bit 1^ in 
the Job Status Word. The /SINGLE switch to the R[UN] command andjthe 
"S" program controlled terminal option allow individual programs to 
control siiigle character activation. The SET TT SINGLE comitand 

i 
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applies to all programs until the SET TT NOSINGLE command is issued. 
If the SET TT NOSINGLE command is in effect, then programs may still 
individually control single character activation with the 
R[UN]/SINGLE switch or the "S" program controlled terminal option. 
In all cases, the program must still set bit 12 in the Job Status 
Word to achieve single character activation. The SET TT SINGLE 
command differs from the R[UN]/SINGLE switch in that it only affects 
setting of single character activation (JSW bit 12), not terminal 
no-wait input (JSW bit 6). The SET TT NOWAIT command may be used to 
allow no-wait terminal input. 

[NO]TAB 

Controls conversion of TAB characters to multiple spaces. TAB should 
be selected with terminals whose hardware can respond to TAB 
characters. When set NOTAB, TAB characters being sent to the 
terminal are replaced by an appropriate number of spaces. 

[NO]TAPE 

TAPE tells TSX-Plus that the terminal line is connected to a paper 
tape, cassette tape, floppy disk or other device that will respond to 
X-ON/X-OFF (CTRL-Q/CTRL-S) control characters to start and stop 
transmission. Setting TAPE mode has three effects: 1) TSX-Plus 
transmits an X-OFF character (CTRL-S) to the terminal when the line 
input buffer fills to the point that there are only 20 free character 
positions remaining; 2) TSX-Plus transmits an X-ON character (CTRL-Q) 
to the terminal when a program begins waiting for more input from the 
line and an X-OFF has previously been sent to the terminal; 3) line- 
e-feed characters are completely ignored unless line-feed is declared 
to be a user-defined activation character — this is done so that 
each line of input may be terminated by both a carriage-return and a 
line-feed. See Chapter 6 for information about how a'program can 
turn tape mode on and off. 

VT50 

Equivalent to the VT52 option. 

VT52 

Tells TSX-Plus that the terminal being used is a VT52 (or VT100 in 
VT52 mode) and also has the effect of SET TT SCOPE, TAB, PAGE, 
NOFORM. 

VT100 

Tells TSX-Plus that the terminal being used is a VT100 (which must be 
operating in VT100 mode — not VT52 compatible mode) and also has the 
effect of SET TT SCOPE, TAB, PAGE, NOFORM. 

[NOJWAIT 

Normally, TSX-Plus blocks the execution of a program that does a 
.TTYIN EMT if no activation character has been received even if the 
program sets bit 6 in the Job Status Word which is supposed to mean 
that the program can do non-blocking .TTYIN character tests. This is 
done to prevent programs from "burning up" CPU time by constantly 
looping back to test for terminal input. If the NOWAIT option is 
specified with the SET TT command, TSX-Plus will honor bit 6 in the 
Job Status Word and allow the program to do non-blocking .TTYINs if 
bit 6 is set. The example program "STEALS" in the section on 
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requesting exclusive system control in Chapter 11 demonstrates the 
program controlled terminal option to allow NOWAIT input. 

All of these terminal options can be given initial settings for each line when 
the TSX-Plus system is generated. Each time a user logs onto a line, the 
initial option settings are used. The options may be altered by using the SET 
command, but when the user logs off, the options revert to their initial 
setting specified in TSGEN. When a user initiates a virtual line, the initial 
flag settings for the virtual line are copied from the current flag settings 
for the user. Subsequent flag changes for a virtual line do not affect flag 
settings for the user's other lines. 


SET UCL 

You can specify the order in which the TSX-Plus command interpreter checks for 
user-defined commands by use of the SET UCL command. This command has four 
forms: 


SET UCL FIRST 
SET UCL MIDDLE 
SET UCL LAST 
SET UCL NONE 

If the SET UCL FIRST command is used, user-defined commands will be processed 
before system commands. This allows user-defined commands to replace system 
commands but makes the processing of system commands slower. This is the 
required setting only if it is necessary to replace some system commands. 

If the SET UCL MIDDLE command is used, user-defined commands are processed 
after system commands but before checking for command files and SAV files with 
names that match the command keyword. Using this setting, it is not possible 
to replace a system command with a user command, but both system commands and 
user-defined commands are processed relatively quickly. This is the recom¬ 
mended setting unless it is desirable to replace system commands. 

If the SET UCL LAST command is used, a command will not be checked to see if it 
is a user-defined command until after it is checked to see if it is a system 
command, the name of a command file on DK, the name of a command file on SY, or 
the name of a SAV file on SY. Using this setting, it is not possible to 
replace a system command with a user command and user commands cannot have the 
same name as command files or SAV files. System commands are processed quickly 
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands 
is slow. This is the appropriate setting only if user-defined commands are 
desired, but command files already exist whose names would conflict with 
user-defined commands. Existing command files which are short and merely 
execute system commands should be replaced by user-defined commands. 

If the SET UCL NONE command is used, user defined commands are never inter¬ 
preted. In this mode, attempts to invoke user-defined commands will result in 
the error: 
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7KM0N-F-Unrecognizable command 

The following list illustrates where the FIRST/MIDDLE/LAST setting causes the 
command interpreter to check for and process user-defined commands: 

FIRST --> 

See if command is a system command 

MIDDLE —> 

Look for command file on DK: with command name 
Look for command file on SY: with command name 
Look for SAV file on SY: with command name 

LAST --> 

See the beginning of this chapter for further information on the command 
interpretation process. 


SET VM 

The SET VM command is used to control the amount of memory available to the VM 
pseudo-device. The SET VM command is normally not necessary as VM will 
automatically calculate the correct base address to use, starting just above 
the last address used by TSX-Plus, and using all physical memory installed 
above that address. The only form of this command is: 

SET VM BASE=nnnnnn 

where "nnnnnn" represents the octal value of bits 6 through 22 of the base 
memory address which VM is allowed to use. For example, in a system with 1.5 
megabyte of memory, to reserve the top 256 Kb of memory for use by VM the value 
of "nnnnnn” should be 50000. This corresponds to a base address for VM of 
5000000. If this command is issued, then VM will use the higher of the address 
specified by "nnnnnn” or the top of TSX-Plus. That is, it is not permitted to 
set the base of VM to include the system overlay regions. 


SET WILDCARDS 

The SET WILDCARDS command is used to control substitution of missing parts of 
file names. The form of the command is: 

SET WILDCARDS option 

where "option” is either IMPLICIT or EXPLICIT. If IMPLICIT is chosen, then 
file specifications which are incomplete will be treated as though the "*" 
character had been typed for the missing part of the specification. The only 
parts of file specifications affected by this substitution are the file name 
and the extension. The device cannot be specified as a wildcard. Most 
keyboard commands which accept file names also accept wildcards. The following 
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table demonstrates the interpretation of various file specifications when 
wildcards have been set IMPLICIT or EXPLICIT. 


Command 

IMPLICIT 

EXPLICIT 

cmd 

TEST.FOR 

cmd TEST.FOR 

cmd 

test.: 

cmd 

TEST.* 

cmd TEST.* 

cmd 

TEST. : 

cmd 

TEST 

cmd TEST.* 

cmd 

TEST 

cmd 

TEST. 

cmd TEST. 

cmd 

TEST. 

cmd 

*. FOR 

cmd *.FOR 

cmd 

*. FOR 

cmd 

.FOR 

cmd *.FOR 

cmd 

.FOR 

cmd 

*.* 

cmd *.* 

cmd 

*.* 

cmd 

* 

cmd *•* 

cmd 

* 

cmd 

.* 

cmd *.* 

cmd 

.* 

cmd 


cmd *.* 

cmd 



where "cmd" is one of the keyboard commands which accepts wildcards in file 
specifications, such as: COPY, DIRECTORY, PRINT, PROTECT, etc. 

The system-wide default setting for wildcard interpretation may be selected in 
TSGEN; see the TSX-Plus System Manager's Guide. 


The SHOW Command 

The SHOW command is used to display information about the state of the system. 
Each form of the SHOW command is described below. 


SHOW ALL 

The SHOW ALL command is equivalent to specifying all of: SHOW DEVICES, SHOW 
ASSIGNS, SHOW JOBS, SHOW TERMINALS, SHOW MEMORY, SHOW SUBSETS, SHOW MOUNTS, 
SHOW RUN-TIMES. 


SHOW ASSIGNS 

The SHOW ASSIGNS command displays information about all logical device 
assignments that are currently in effect. 

Example: 


.SHOW ASSIGNS 


Assignments: 

SY 

—> 

DLO: 

CBL 

--> 

RKO: 

TMP 

—> 

DL3: 

DK 

--> 

LDO: 
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SHOW CACHE 

The SHOW CACHE command reports the total number of blocks available in the 
generalized data cache buffer. 

Example: 


. SHOW CACHE 

Number of blocks in data cache = 1000 


SHOW COMMANDS 

The SHOW COMMANDS command is used to display the currently available user- 
defined command definitions. See the beginning of this chapter for more 
information on declaring and using user-defined commands. Note that escape 
characters embedded in commands are represented by a dollar sign ( $ ). 

Example: 

. SHOW COMMANDS 
C100 
DEF 
EXAM 
KPAD 
LOG 
NEW 

NOKPAD 
N0L0G 

Q 

SUB 
TOME 
WORK 


SHOW CONFIGURATION 

The SHOW CONFIGURATION causes a display of certain hardware and operating 
system characteristics. 


DISPLAY $[H$[J 
ASS ~ DK 
R KED ~/I 
DISPLAY $= 

SET LOG FILE=~ 

R DIR ~/D 
DISPLAY $> 

SET LOG CLOSE 
"SPOOL LP,STAT 
"SH SUB 

DISMO LD0\_ASS DL2 DK\_SH SUB 

DISMO LD0\ MOU LDO DL2:WORK DK\_SH SUB 


SHOW CORTIM 

The SHOW CORTIM command displays the current value of the system parameter 
CORTIM. See the TSX-Plus System Manager's Guide for more information on the 
significance of the CORTIM parameter. 
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Example: 


.SHOW CORTIM 
2 


SHOW DEVICES 

The SHOW DEVICES command displays information about which devices were 
specified as being available when TSX-Plus was generated. For each device the 
following items of information are displayed: 

1. Device name 

2. Device status word (See the RT-11 Programmer's Reference 
Manual, .DSTATUS request, for a description of this value.) 

3. Device handler base address 

4. Device handler size (decimal bytes) 

5. Device CSR (Control and Status Register) address 

6. Device interrupt vector(s) address 

The CSR and vector values are only displayed if the user issuing the SHOW 
DEVICES command has operator privilege. Some of this information is not 
displayed for pseudo-devices such as TT, NL, and LD. 

Example: 


.SHOW DEVICES 


Device 

Status 

Handler 

base 

Handler 

size 

CSR 

Vector 

TT 

DM 

000004 

102423 

065302 

1316 

177440 

210 

MT 

016011 

067746 

3844 

172520 

224 

DX 

102022 

077352 

594 

177170 

264 

LP 

020003 

100474 

318 

177514 

200 

NL 

LD 

000025 

102446 

101172 

58 




SHOW H1PRCT 

The SHOW HIPRCT command displays the current value of the system parameter 
HIPRCT. See the TSX-Plus System Manager's Guide for more information on the 
significance of the HIPRCT parameter. 

Example: 

.SHOW HIPRCT 
40 
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SHOW INTIPC 

The SHOW INTIOC command displays the current value of the system parameter 
INTIOC. See the TSX-Plus System Manager's Guide for more information on the 
significance of the INTIOC parameter. 

Example: 

.SHOW INTIOC 
30 


SHOW JOBS 

The SHOW JOBS command displays information about jobs that are currently logged 
onto the system. The information displayed by this command is identical to 
that displayed by the SYSTAT command. 


SHOW MEMORY 

The SHOW MEMORY command displays information about memory usage including the 
total installed memory on the machine, the size of TSX-Plus and handlers, the 
memory space available to user jobs and the current job memory allocation and 
maximum authorized size. It also lists the size of the swappable job context 
area which is a system table associated with each job. 

Example: 

. SHOW MEMORY 

Total installed memory = 1280Kb 
Size of unmapped TSX and handlers = 38Kb 
Size of mapped TSX system regions = 38Kb 
Total size of TSX and mapped data = 80Kb 
Size of sharable run-time systems = 0Kb 
Size of data cache buffer area = 516Kb 
Space available for user jobs = 683Kb 
Swappable context area for each job = 4Kb 
Current job memory limit = 56Kb 
Maximum job memory limit = 64Kb 


SHOW MOUNTS 

The SHOW MOUNTS command displays the names of those devices that have been 
mounted by use of the MOUNT command and whose directories are being cached. 
TSX-Plus maintains a list of which jobs have mounted each device. This list is 
used with the INITIALIZE and SQUEEZE commands to reduce the chance of data 
destruction by altering a device directory while another job has a file open on 
the device. For logical subset disks, the name of the file which contains the 
device is also shown. Note that with nested logical subset disks, the table 
formatting is relaxed. 
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Example: 


. SHOW MOUNTS 

Device Associated jobs 


DLO: 

1 

2 

DL1: 

1 

6 

DL2:SMADA 

8 


DL3: 

2 

11 

DL3:WORK 

11 


DL3:WORK:TEMP 

11 

DL3:MANUAL 

2 



SHOW NUMPC 

The SHOW NUMDC command displays the current value of the system parameter 
NUMDC. See the TSX-Plus System Manager's Guide for more information on the 
significance of the NUMDC parameter. 

Example: 

.SHOW NUMDC 
0 


SHOW PRIORITY 

The SHOW PRIORITY command displays the current and maximum priority values for 
a job. In addition, the range of priority values which are used for high and 
low fixed priority jobs is shown. See Appendix H for further information about 
job execution priorities. 

Example: 


. SHOW PRIORITY 

Current priority = 50; maximum authorized priority = 127 
Low priority range = 0 to 19 
High priority range = 80 to 127 


SHOW QUANxx 

The SHOW QUANxx command is used to display the current value of various system 
tuning parameters. The parameters which may be shown are: QUANO, QUANl, 
QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3. Related tuning parameters which may 
also be shown are: CACHE, CORTIM, HIPRCT, INTIOC, and NUMDC. See the TSX-Plus 
System Manager's Guide for more information on the significance of the various 
system tuning parameters. 
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Example: 


.SHOW QUAN3 
20 


SHOW QUEUE 

The SHOW QUEUE command displays information about print files in the spool 
queue. The following information is displayed for each print file in the 
queue: name of the device the file is queued for; an asterisk if the file is 

currently being printed; the name of the file if a file name was specified with 
the .ENTER otherwise the name of the program that created the file; the name 
of the form on which the file is to be printed; the number of blocks in the 
file remaining to be printed this will decrease as the file is printed. For 

more information on printer spooling, see Chapter 5. 

Example: 


.SHOW QUEUE 


Dev 

Job 

File 

Form 

Blocks 

LP * 

1 

PLT50 

STD 

244 

LP 

5 

EXTERN 

STD 

5 

LP 

5 

PAYROL 

F0RM3 

35 


SHOW RUN-TIMES 

The SHOW RUN-TIMES command causes the display of the names o.f the shared 
run-time systems that were loaded with the system. 

Example: 

.SHOW RUN-TIMES 

CBRTS 

RTCOM 


SHOW SUBSETS 

The SHOW SUBSETS command is used to obtain information about logical subset 
disks which have been mounted. Only the logical subset disks which have been 
mounted by the user are shown; those mounted by other users are not included. 
The name of the logical subset disk, the file with which it is associated, the 
file size, and an optional asterisk are displayed. If present, the asterisk 
indicates that the file associated with the logical subset disk is missing. In 
order to DISMOUNT a logical subset disk which is associated with a missing 
file, it is necessary to create or copy the missing file to the appropriate 
device. See the MOUNT and DISMOUNT commands and Appendix G for more infor¬ 
mation on logical subset disks. 
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Example: 


.SHOW SUBSETS 

LDO ~> DL1:MANUAL.DSK[2601] 
LD2 —> LDO:SUB.DSK[100] * 


SHOW TERMINALS 

The SHOW TERMINALS command gives a display of the parameters of all primary 
time-sharing terminal lines defined to TSX-Plus during system generation along 
with some current characteristics. 

Example: 

.SHOW TERMINALS 


Unit 

Type 

Vector 

CSR 

Terminal 

Speed 

Active 

User 

1 

Operator 

DL 

060 

177560 

VT100 

N/A 

Yes 

SYSMGR 

2 

Local 

DL 

310 

176510 

VT100 

N/A 

No 


3 

Local 

DL 

320 

176520 

LA120 

N/A 

Yes 

SMADA 

4* 

Local 

DZ-0 

300 

160040 

VT100 

9600 

Yes 

GREG 

5 

Local 

DZ-1 

300 

160040 

VT100 

9600 

No 


6 

Remote 

DZ-3 

300 

160040 

VT52 

1200 

No 



The unit number indicates the number assigned to each line (determined by the 
order of declaration during system generation). The line which issued the 
command is marked with an asterisk. The type of line may be: Operator - the 
line which was declared to be the operator's console during TSX-Plus system 
generation; Remote - any line which has been declared to be attached to a modem 
during system generation; or Local - all other lines. The interface hardware 
is indicated in the Vector column as either a DL(V)11 serial interface or a 
DZ(V)11 multiplexor. DZ lines are further identified with the port number to 
which the line is attached. The Vector and CSR addresses are those declared 
during system generation. The Terminal identification is that which has been 
declared to TSX-Plus either during system generation or via a later SET TT 
<type> command. The Speed column indicates the baud rate specified for DZ type 
lines; it is not available for DL type lines. Lines which are currently logged 
on are marked with a "Yes" in the Active column and the owner is identified in 
the User column if possible. 


SHOW USE 

The SHOW USE command causes display of the accumulated connect time and CPU 
usage for the current job since logon. The SHOW USE command is equivalent to 
the USE command. 
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Example: 

.SHOW USE 

Connect=00:50:00 CPU=00:00:23 


The SPOOL Command 

The SPOOL Command is used to control the operation of the spooling system. It 
may only be used if device spooling is enabled when the system is generated. 
The form of the SPOOL command is: 

SPOOL device function,parameter 

where "device" is the name of a device that was specified to be spooled when 
the system was generated, "function" denotes what function is to be performed, 
and "parameter" provides additional information for some functions. See 
Chapter 5 for further information on the SPOOL command. 


The SQUEEZE Command 

The TSX-Plus SQUEEZE command has the same form and options as the RT-11 SQUEEZE 
command. However, the system device (booted device when TSX-Plus is started) 
may not be squeezed while running TSX—Plus. If it is necessary to squeeze the 
system device, it must be done from RT-11. The following error message 
appears: 

?KMON-F-This operation not legal with SY (system) device 


A device cannot be squeezed if any other user has MOUNTed the device. Attempts 
to SQUEEZE a device which is mounted by another user will result in the error 
message: 

7KM0N-F-Device is mounted by another user 

The SHOW MOUNTS command may be used to determine which other jobs have the 
device mounted. If the device is mounted only by the job which squeezes it, 
then the directory and data caches are cleared after the operation and caching 
is resumed. 

If terminal logging is being done (see the SET LOG command) and a log file is 
open on the device being squeezed, the log file is automatically closed and the 
following warning message appears: 

?KMON-W-Closing log file 

Warning: It is still possible to write to a device without first mounting it. 
If one user has a file open on a device while another user squeezes the device, 
the possibility of severe data corruption exists. If the user with the open 
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file writes to the disk during or after the squeeze operation, the data will be 
directed to locations on the disk according to the previous directory infor¬ 
mation. When the disk is squeezed, these locations are no longer appropriate 
and write operations will probably corrupt other files. Never squeeze a disk 
to which another user may be writing data. As a defensive measure, always 
MOUNT any device which you plan to use. 


The SYSTAT Command 

The SYSTAT (SYstem STATus) command displays information about the performance 
of the system and information about each logged-on job. The first line 
indicates the amount of time since TSX-Plus was started or the RESET command 
was issued. The second line of the system performance information shows a 
breakdown of the percent of total time spent running user jobs, waiting for 
user I/O, waiting for swapping I/O and waiting for something to do (idle time). 
These percentages should add up to approximately 100% (less rounding errors). 
The third line of system performance information shows the percent of the total 
time that some user I/O and swapping I/O was being performed. The percentages 
on this line are not expected to sum to 100 because they simply indicate how 
much of the time some I/O was taking place without considering whether jobs 
were running while the I/O was going on. The difference between the I/O 
percentages on the second line and the I/O wait percentages on the first line 
is a measure of the amount of overlap of job execution with I/O that took 
place. The RESET keyboard command may be used to reset these statistics so 
that the statistics may be gathered over a desired interval of system execu¬ 
tion. 

The information displayed for running jobs consists of one line per job. The 
first item is the job number, followed by an asterisk for the line to which you 
are currently attached. The next item indicates the primary line and virtual 
line number for each job. If the job is a primary line, then the line number 
will correspond to the job number and the number in parentheses will be zero - 
indicating relative virtual job number 0. If the job is a virtual job, the 
line number will indicate the primary line from which it was started and the 
virtual job number relative to the primary line in parentheses. Detached jobs 
will be marked by "Det.". The next item is the current priority for each job. 
A two-character state code is printed next, indicating the current state of the 
job. The state codes and their meanings are as follows: 
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State Meaning 


HI High priority non-interactive run state 

IN Interactive state 

10 Waiting for non-terminal I/O to finish 

L0 Fixed-low-priority run state 

MI Waiting for mapped I/O buffer 

MS Waiting for a message 

RN Normal priority non-interactive run state 

RT Fixed-high-priority run state 

SF Waiting for access to a shared file 

SL Doing a timed wait (.TWAIT) or .SPND 

SP Waiting for free spool block or file entry 

TI Waiting for input from the terminal 

TO Waiting for the terminal to print output 

US Waiting for access to file management module 

The characters "-Swap" are printed following the state code if the job is 
currently swapped out of memory. "-Lock" is displayed by the state code if the 
job has locked itself in memory. The number of K-bytes of memory space used by 
the job, shown next, includes ordinary job space, extended memory regions and 
the job context block (currently 4Kb). This is followed by the connect time 
and CPU time used so far by the job, and the name of the program being run on 
the line. Except for detached jobs, which are not associated with any 
particular user or line, the last item indicates the user name. The user name 
may be blank. 

Example; 


. SYSTAT 

Uptime: 05:34:29 

System use: Run=10%, I/0-wait=8%, Swap-wait=0%, Idle=81% 

I/O Activity: User 1/0=10%, Swapping 1/0=0% 


Job 

Line 

Pri 

State 

Size 

Connect 

CPU time 

Program 

User name 

i 

1(0) 

50 

TI-Swap 

33Kb 

05:35:00 

00:03:40 

KM0N 

SYSMGR 

2 

2(0) 

40 

TI 

32Kb 

01:53:00 

00:01:36 

KED 

ANDY 

5 

5(0) 

84 

SL-Lock 

16Kb 

01:00:00 

00:03:17 

LAB 3 

V0LPE 

8 

8(0) 

50 

RN 

34Kb 

05:24:00 

00:00:33 

COBOL 

MITCHELL 

10 

Det. 

50 

MS-Swap 

60Kb 

05:35:00 

00:00:00 

RTS0RT 


11* 

2(1) 

50 

IN 

33Kb 

01:53:00 

00:01:00 

KM0N 

ANDY 

The TECO Command 








The TEC0 command is used to initiate an editing session with the TEC0 editor. 
The TSX-Plus TECO command is equivalent to the RT-11 TEC0 command. 
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The TIME Command 

The TSX-Plus TIME command has the same form and options as the RT-11 TIME 
command. Operator command privilege is required to set the time. 


The TYPE Command 

The TSX-Plus TYPE command has the same form and options as the RT-11 TYPE 
command. 


The UCL Command 

The UCL command is equivalent to the SHOW COMMANDS command. 


The UNPROTECT Command 

The UNPROTECT command is used to clear file protection status. The TSX-Plus 
UNPROTECT command has the same form and options as the RT-11 UNPROTECT command. 


The USE Command 

The USE command displays the accumulated connect time and CPU usage since 
log-on. 

Example: 

. USE 

Connect=02:25:00 CPU=00:02:19 


The WHO Command 

The WHO command is used to display information about the system status and 
logged-on jobs. The WHO command is equivalent to the SYSTAT command. 


The $ST0P Command 

The $ST0P command is used to halt the execution of TSX-Plus. On some hardware 
configurations, this may also reboot RT-11. The form of the command is: 

$ST0P 

The $ST0P command forces an immediate logoff of all users before stopping 
TSX-Plus. Operator privilege is required to use this command. If other users 
are logged on, the system will request verification before stopping. Any 
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response beginning with "Y" or "y" will halt TSX-Plus; any other response will 
return to the monitor. For example: 


. $STOP 

Other users are logged on. 

Are you sure you want to stop the system?Y 

Connect=01:14:22 CPU=00:11:15 


The $SHUTDOWN Command 

The $ SHUTDOWN command is similar to the $STOP command in that it is used to 

stop TSX-Plus and may return control to RT-11. However, it differs from $STOP 

in the manner in which it stops TSX-Plus. $STOP forces the immediate logoff of 
all users, $SHUTDOWN does not. Rather, it sets a flag which prevents any new 
users from logging on and then waits for all logged on users to log off. When 

the last user logs off, TSX—Plus is stopped and control may return to RT-11. 

The form of this command is: 

$SHUTDOWN 

Operator privilege is required to use this command. 

2.5 RT-11 Commands not supported by TSX-Plus 

The following RT-11 keyboard commands are not supported by TSX-Plus and are 
ignored if issued: CLOSE, GT, INSTALL, LOAD, REMOVE, RESUME, SUSPEND, UNLOAD. 

The following RT-11 keyboard commands are not supported by TSX-Plus and will 
result in the "Unrecognizable command" error message: ABORT, B, D, E, FRUN, 
GET, REENTER, SAVE, SRUN, START. 

The following keyboard commands have different effects under RT-11 and 
TSX-Plus: BOOT, RESET. 

The following switches are not supported by TSX-Plus with the DIBOL, 
COMPILE/DIBOL or EXECUTE/DIBOL commands: /BUFFERING, /LOG, /PAGE, or /TABLES. 

The following SET options are not supported by TSX-Plus: EL, EXIT, or USR. 
The following SET TT options are not supported by TSX-Plus: CONSOL, [NOJCRLF, 
[NO]FB, or WIDTH. 
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Certain series of keyboard commands may be executed together regularly, or may 
be so complex that it is desirable to edit and proofread them before execution. 
These needs are met by the facility known as indirect command files. These are 
files containing a set of keyboard commands to be executed together. Command 
files are invoked by providing the file name preceded by an symbol in 
response to the keyboard monitor prompt. Command files may also be invoked 
without the if their names do not conflict with system commands. See the 
description of keyboard command interpretation in Chapter 2 for more infor¬ 
mation on how command files may be initiated. 

TSX-Plus allows the specification of parameter strings to be inserted in a 
command file. The parameters are stored by TSX-Plus and inserted in the text 
of the command file at selected points as the command file is processed. 
TSX-Plus also allows program data as well as system commands to be placed in a 
command file. Under TSX-Plus it is possible to set up a command file so that 
any request for data from device "TT" comes from the command file. This allows 
EDIT and TECO (but not KED) commands to be placed in a command file. 

Command files may be executed either using normal TSX—Plus interpretation or 
under the control of the IND utility. Either type of control may be specified 
either implicitly or explicitly. The keyboard command SET KMON [NO]IND selects 
the desired implicit control of command files. If KMON is set IND, then 
command files will normally execute under the control of the IND program. If 
KMON is set NOIND, then command files will normally execute under TSX-Plus 
control. Regardless of the setting of KMON, a file may be executed under 
control of IND by typing: 

IND file 

Regardless of the setting of KMON, a file may be started as a normal command 
file (not under the control of IND) by typing: 

$@ file 
Examples: 


1. Execute the command file DK:DAILY.COM under control of the IND 
utility regardless of the setting of KMON: 

. IND DAILY 

2. Execute the command file DLl:WEEKLY.COM under normal TSX-Plus control 
regardless of the setting of KMON: 

.$@DL1:WEEKLY 
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3.1 Invoking command files 

A command file is invoked by typing: 

^filename [paraml [param2 ... [param6]]]]]] 

where filename is the name of the command file and "paraml", "param2", etc. 
are optional parameter string arguments to the command file. The default 
extension for a command file is "COM". 

When the name of a command file does not conflict with a system command, the 
command file may be invoked by typing: 

filename [paraml,...param6] 

That is, the @ may be left out. With or without the "@" sign, if no device 
is specified device "DK" is first searched for the command file. Then, only 
without the "@" sign, if the named file is not found, then TSX-Plus attempts to 
locate the command file on device "SY". See Chapter 2 for a description of the 
steps used by TSX-Plus to interpret keyboard commands. Listing control for 
command files differs whether the "@" sign is used or not. If the "@" is used, 
then listing is controlled by the current value of the SET TT [NOJQUIET option. 
If no "@" is used, then listing is disabled — as if a SET TT QUIET had been 
issued. In either case, the command file itself can control its own listing 
status with a SET TT [NOJQUIET command or with the control characters described 
later in this chapter. 

3.2 Parameter strings 


Parameter strings are normally delimited by spaces. Thus in the command: 
0TSTRUN ABC 123.45 2/3 

the string "ABC" is parameter 1, "123.45" is parameter 2 and "2/3" is parameter 
3. In some cases it may be desirable to include spaces as part of a parameter 
string. If this is to be done, the first parameter must begin with the 
character "\" (left leaning slash), and the left-slash must be used as the 
parameter delimiter rather than spaces. For example, in the command line: 

0TSTRUN \A STRING\OF PEARLS 

parameter 1 is "A STRING" and parameter 2 is "OF PEARLS". 

Up to six parameter strings may be specified when the command file is started. 
The total number of characters in the combined parameter strings may not exceed 
60. 
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Parameter strings are inserted into the command file during execution at 
locations specified by an up-arrow ("~"). The parameter to be inserted is 
designated by a digit (1 to 6) immediately following the . During execution 
of the command file, the "up-arrow-digit” sequence is replaced by the parameter 
string passed to the command file in the position specified by the digit. If a 
parameter string is called for that was not specified when the command file was 
invoked, the up-arrow-digit will be ignored and no characters will be inserted 
in their place. For example, consider the following command file named 
TEST.COM: 

R ~1 
~ 3=~2 

When this command file is invoked with the following command: 

@TEST FORTRAN PROG 

the command file is executed as if it contained the commands: 

R FORTRAN 
=PR0G 

Command files may be nested. That is, one command file may call another 
command file. When such a call occurs, the parameter strings for the outer 
level (calling) command file are stored on a stack in TSX-Plus and then the 
parameter strings for the called command file are set up. When the called 
command file finishes, the parameters for the calling command file are 
restored. The maximum depth of nesting is governed by the size of the 
parameter string stack and the length of the actual parameter strings. A 
nesting depth of 3 can be reached even with very long parameter strings. If no 
parameters are specified, the nesting depth may go to about 7 levels. 

The command file listing status (SET TT [NOJQUIET) is also stacked as command 
files are nested. This means that an inner nested command file may have its 
listing turned on or off. When its execution is completed and control returns 
to the next outer level command file, the listing control is reset to the state 
in effect when the inner command file was called. This is not done for the 
outer-most command file, however, so the SET TT [N0]QUIET state in effect on 
completion of the outer level command file remains in effect when control is 
returned to the keyboard monitor. 

3.3 Comments in command files 


Comments may be included in command files following an exclamation point ("!"). 
Anything on a line in a command file following an exclamation point will be 
treated as comment. For example, in a command file containing the lines: 
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DISPLAY Watch out! Files may be destroyed. 

PAUSE Hit RETURN to proceed !Requires operator response 

the resulting output would be: 

Watch out 

PAUSE Hit RETURN to proceed 

» 

When an exclamation mark ("!") is used in a command file line to be input as 
data to a program, then the exclamation mark and all text following it on the 
input line are not passed to the program. 

3.4 Command file control characters 

Several combinations of characters take on special meaning when they are found 
within a command file. The up-arrow character ) followed by a letter is 

replaced by the control character corresponding to the letter specified. Thus 
" A C" becomes control-C. The escape character may be represented by up-arrow, 
dollar sign The up-arrow character itself may be represented in the 

command file by preceding it with another up—arrow ( ). 

Several character combinations act as special commands to influence the 
execution of the command file. These commands take effect at the point of 
their occurrence in the command file. The characters in these special 
sequences are not passed to programs. 

Command 

Sequence Function 


Stop listing command file. This has the same effect as SET TT 
QUIET, except that it only applies to the current command file. 

Start listing command file. This has the same effect as SET TT 
NOQUIET except that it only applies to the current command file. 

Suppress all terminal output. Both the command file listing and 
any program terminal output are suppressed. The and 

command sequences restart program generated output. 

Accept all terminal input from the command file. Command file 
data is normally only passed to programs which request lines of 
input (using the EMT calls: .GTLIN, .CSISPC and .CSIGEN). 
RT-11 handles command file data in this manner. Programs called 
by a command file which request terminal input with the EMT 
calls .TTYIN or .READ normally still expect to get this from the 
terminal and cannot use command file data as input to these 
requests. The command sequence causes all subsequent 

requests for terminal input to come from the command file 
regardless of which EMT is used. This allows data for appli- 
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cation programs to be placed in a command file. It also allows 
commands for TECO and EDIT to be placed in a command file. This 
command only affects input requests that occur after TSX-Plus 
reads the sequence. See also the description in Chapter 6 
of the "N M and ”0" program controlled terminal options that 
affect command file input. 

Return to standard data mode. Subsequent command file data will 
only be passed to programs which do .GTLIN, .CSISPC or .CSIGEN 
EMTs (standard RT-11 mode). 

~Z Control-Z is translated to control-C in command files. 

3.5 PAUSE Command 


The PAUSE command is provided to suspend the execution of a command file while 
the operator performs some manual operation. The form of the PAUSE command is: 

PAUSE comments 

where "comments” may be any string of characters. When a PAUSE command is 
executed, the PAUSE command is displayed at the terminal followed by "»". 
Execution of the command file is then suspended until carriage return is typed. 

3.6 DISPLAY Command 


The DISPLAY command causes a line of text to be displayed at the terminal. The 
form of the DISPLAY command is: 

DISPLAY comments 

where "comments" may be any line of text to be printed at the terminal. This 
is useful to mark progress through command files running in "quiet" mode (not 
being listed). 
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4. VIRTUAL TIME-SHARING LINES AND DETACHED JOBS 


4.1 Virtual Lines 

TSX-Plus provides a facility known as "virtual lines" which allows one 
time-sharing user to simultaneously control several running programs from a 
single terminal. When initially logging on to TSX—Plus, the user is connected 
to the "primary" time-sharing line, also called virtual line number 0 (zero). 
At any time, the user may switch to a different virtual line. This has the 
effect of logically disconnecting the time-sharing terminal from the current 
virtual line and connecting it to a different logical line. Note that when 
normal priority jobs are disconnected from a terminal by switching to a virtual 
line, the priority of the disconnected job is reduced by an amount selected 
during system generation. Jobs in either the fixed-high- or fixed-low-priority 
ranges do not suffer this priority reduction. 

If a program is running when the switch is made, its execution is not affected 
(but it is given a lower CPU priority). If a program is running on a line that 
is not not currently connected to the terminal and that program writes output 
to the terminal, the output is not displayed at the terminal, but is instead 
stored in a terminal output buffer. When this buffer is filled, the program is 
suspended (and the job may be swapped out of memory) until the terminal is 
reconnected to the virtual line. On a disconnected virtual line, if the output 
buffer becomes full or if a program requests terminal input, the bell is rung 
on the line which is currently connected to the terminal to indicate that a 
virtual line needs service. 

To switch to a virtual line, type control-W (hold down CTRL key and press W) 
followed by a single digit (do not hold down CTRL while typing the digit). The 
digit identifies which virtual line the user wishes to access. Other, users may 
be using virtual lines of the same relative number without conflict. The 
CTRL-W digit sequence may be entered at any time - even in the middle of a line 
of input. The command takes effect immediately and leaves the old line in an 
undisturbed state. (On later return to the primary line, CTRL-R may be used to 
display a partial input line which had already been typed.) TSX-Plus responds 
to CTRL-W, digit by printing "n>" on the terminal, where "n" is the relative 
number of the virtual line that has just been accessed. Note that the relative 
virtual line number does not correspond to the job number. The SYSTAT command 
may be used to determine the job number and, for virtual lines, to determine 
the primary line from which virtual lines were started and their virtual line 
numbers relative to the primary line. The primary line can always be accessed 
with the sequence "<CTRL-W>0", since the primary line is virtual line number 0. 
(Note that the system manager may select a signal character other than 
control-W to indicate a request to switch to a virtual line.) 

If a start-up command file was specified for the primary line, it will also be 
executed when the virtual line is initiated. If the LOGON program is run as 
part of the start-up command file for a virtual line, it will automatically log 
the user on to the account specified when logging onto the primary line. 
Therefore, logical assignments made in a start-up or LOGON command file are 
defined for the virtual line. However, other logical assignments are not 
inherited by the virtual line. Any user defined commands in effect for the 
primary line are inherited by a virtual line when it is started. 


- 81 - 



















Virtual Lines & Detached Jobs 


The user logs off a virtual line by typing the "OFF" command* When a user logs 
off a virtual line other than the primary line, that virtual line is returned 
to the pool of free lines and the user is automatically reconnected to the 
primary line. When a user logs off the primary line, not only is the primary 
line released, but any virtual lines the user may have been using are also 
released, and the user is disconnected from the system. Note that it is 
possible (and frequently desirable) to switch back and forth between the 
primary line and one or more virtual lines without logging off any. 

The total number of virtual lines and the maximum number of virtual lines which 
any user may utilize at a given time are determined by the system manager. An 
attempt to log on to a virtual line number higher than the maximum allowed for 
each user, is ignored. The CTRL-W, digit sequence is also ignored if the user 
is already connected to the maximum number of virtual lines allowed or if no 
free virtual lines are available. 

Virtual lines are quite useful in situations where the user wishes to execute a 
long "number crunching" job without tying up a line. Simply start the long job 
and switch to another virtual line. The CPU priority of the disconnected job 
is reduced so that it interferes little with normal time-sharing operations, 
but rather "soaks up" idle CPU time. Such low priority jobs run only when no 
high priority jobs are running. 

The keypad editors KED and K52 use the CTRL-W key to repaint the screen. Under 
TSX-Plus, use two successive CTRL-W's to repaint the screen with these editors. 
A conflict arises when switching to a virtual line while in a keypad editor and 
performing another editing job on the second virtual line. When exiting the 
second edit job, the editor automatically restores the terminal from alternate 
(application) keypad mode to numeric keypad mode. Then, on returning to the 
first editing job, it is not possible to use keypad commands since the keys no 
longer generate the correct sequences. To avoid this, either do not use keypad 
editors on more than one virtual line simultaneously, or restore the terminal 
to alternate keypad mode before returning to the original editing job. To set 
either VT-100 or VT-52 type terminals to the alternate keypad mode, send the 
two character sequence "<ESC>=" to the terminal. 

4.2 Detached jobs 

The TSX-Plus Detached job facility is similar to the virtual line facility: 
they both allow a timesharing user to execute several jobs simultaneously. The 
major difference between detached jobs and virtual lines is that you may switch 
back and forth among virtual lines, but once a detached job is started it is 
dissociated from any terminal. Detached jobs operate more like a "batch" 
facility. ALL terminal input for a detached job must come from a command file. 
Any terminal output generated by a detached job is discarded. However, 
terminal logging may be enabled for detached jobs to accept their terminal 
output; see the SET LOG command. 
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The differences between virtual lines and detached jobs are summarized below. 

1. With virtual lines, terminal communication may be switched between 
several running jobs. A detached job must receive all its terminal 
input from a command file and any terminal output it generates is 
discarded (unless terminal logging directs the output to a log file). 
If a detached job requests terminal input and is unable to obtain it 
from a command file, the job is terminated. 

2. Virtual lines are "owned” by a physical line. When the physical line 

logs off, the virtual lines also log off. Detached jobs are not 

associated with any physical line. Once started, any or all 

time—sharing users may log off without affecting detached jobs. 

3. Detached jobs may be started automatically when TSX-Plus is initi¬ 
ated. Virtual line jobs must be started by time-sharing users after 
TSX-Plus is running. 

4. When a detached job reaches the end of its command file and asks for 
more terminal input, the job is aborted and the detached job slot is 
freed. Virtual lines wait for more input. 

There are three ways to start detached jobs: 1) during system generation 

specify a command file to be started as a detached job whenever TSX-Plus is 
started; 2) use the keyboard DETACH command; 3) use the TSX-Plus EMT to start a 
detached job from a running program. Detached jobs that are initiated 

automatically when the system is started run with operator privilege. Detached 

jobs initiated by use of the DETACH command or the EMT inherit the privilege of 
the user starting them. 


4.2.1 The DETACH command. 

The DETACH command is used to start a detached job, check its status and abort 
the job. The system manager may restrict the use of the DETACH command. 

4.2.1.1 Starting a detached job: The form of the DETACH command used to start a 
detached job is: 

DETACH file-spec 

where "file-spec" is the name of a command file to be executed as a detached 
job. The default device is "SY:" and the default extension is "COM". The 
default disk "DK" is not used because no logical assignments are passed to the 
detached job, either in the detach command itself or in the command file 
started with it. When a request is made to start a detached job, TSX-Plus 
searches for a free detached job slot. The total number of such job slots is 
established when TSX-Plus is generated. If a free slot is found, the job is 
started and a message is printed saying which job slot was used. This number 
may be used later to reference the detached job. The SYSTAT command ^ also 
indicates detached job line numbers and flags detached jobs with Det. . A 


-83- 




















p 


o 







Virtual Lines & Detached Jobs 


detached job started by use of the DETACH command inherits the privileges (but 
not any logical assignments nor any logical subset disks declared after logon) 
of the user who is starting the job. If "file-spec" is preceded by the symbol 
then the first line of the command file will be used by the detached job, 
but any remaining commands in the file will be associated with the job 
currently connected to the terminal. 

Neither the DETACH command itself nor the command file started with it inherit 
any logical device assignments. 

Examples: 

1. Start a command file "SY:PURGE.COM" as a detached job. 

. DETACH PURGE 
Job started on line #9 

2. Start a command file named "RKl:STATS.NEW". 

. DETACH RKl:STATS.NEW 
Job started on line #8 

3. Start the first line of "SY:MAKIT.COM" as a detached job, 
and use subsequent lines as an ordinary command file. 

. DETACH @MAKIT 
Job started on line #9 

The system manager determines the number of slots available for detached jobs 
and who may use detached jobs. The job numbers assigned to detached jobs start 
after the slots reserved for primary time-sharing lines. Virtual lines are 
assigned line numbers above any slots reserved for detached jobs. 

4.2.1.2 Checking the status of a detached job: The form of the DETACH command 
used to check the status of a detached job is: 

DETACH/CHECK line-number 

where "line-number" is the job slot number listed when the job was started. 
TSX-Plus displays the status (active or free) of the detached job. 

Examples: 

1. Check the status of the job on line #4. 

. DETACH/CHECK ^ 

Line is active 
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2. Check the status of the job on line //5. 

. DETACH/CHECK 5 
Line is free 

4»2.1.3 Aborting a_ detached job: The form of the DETACH command used to abort 
a running detached job is: 

DETACH/KILL line-number 

where "line-number" is the job slot number listed when the job was started. 
For example, to kill the detached job on line #4: 

. DETACH/KILL 4 
Job aborted 

4.2.2 Detached job control EMTs. 

TSX-Plus provides a set of EMTs that can be used to control the operation of 
detached jobs. Using these EMTs it is possible to start a detached job, kill a 
detached job and check the status of a detached job. 

4.2.2.1 Starting A Detached Job: This EMT can be used to start the execution 
of a detached job. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,132 
.WORD name-address 

where "name-address" is the address of an area containing the name of the 
command file to be started as a detached job. The command file name must be 
stored in ASCIZ form and may contain an extension. If a free detached job line 
is available, the specified command file is initiated as a detached job and the 
number of the detached job line is returned in RO. A detached job started by 
use of this EMT inherits the privileges of the job that is executing the EMT. 
If there are no free detached job lines, the carry bit will be set on return. 

Example: 

.TITLE STRTDJ 
.ENABL LC 

;Start a job on a TSX-Plus detached line 

CR = 15 

LF = 12 

ERRBYT =52 



-85- 

























Virtual Lines & Detached Jobs 


.MCALL .ENTER,.WRITW,.CLOSE,.PRINT,.EXIT 
START: CLR R1 ;Channel number 


;No .FETCH is necessary under TSX-Plus, handlers are always resident. 


1$: .ENTER 

#AREA,R1, //FILR50 

,//1 ;Open a one block file 



;on first free channel. 

BCC 

2$ 

;Branch on successful .ENTER 

TSTB 

@//ERRBYT 

;Why didn't .ENTER work? 

BNE 

NOROOM 

;Error = 1 :not enough room for file 

INC 

Rl 

;Try next higher channel 

CMP 

Rl,#17 

;Last channel? .CDFN not supported by 



;TSX-Plus, so legal channels are 0-15. 

BLE 

1$ 

;0K, retry on next channel 

.PRINT 

//NCA 

;Ran out of channels 

BR 

DONE 


2$: .WRITW 

#AREA,R1,//COMNDS 

,//«CMDEND-C0MNDS-fl>/2>, #0 

BCS 

WRTERR 

;Bad write? 

.CLOSE 

Rl 

;Close the file 

MOV 

//STRTDJ, RO 

;Point to EMT arguments to 

EMT 

375 

;Start the detached job 

BCS 

DTCHER 

;Bad start of detached job? 

BR 

DONE 


NOROOM: .PRINT 

#NER 

;Not enough room error 

BR 

DONE 


WRTERR: .PRINT 

//BADWRT 

;.WRITW error 

.CLOSE 

Rl 


BR 

DONE 


DTCHER: .PRINT 

//BADDET 

;STRTDJ error 

DONE: .EXIT 



AREA: .BLKW 

5 

;EMT Argument area 

STRTDJ: .BYTE 

0,132 

;EMT arguments to start a detached job 

.WORD 

FILNAM 

;Pointer to name of command file 

.NLIST 

BEX 


FILR50: .RAD50 

/SY CKSTATCOM/ 

;RAD50 name of command file to be detached 

FILNAM: .ASCIZ 

/SY:CKSTAT.COM/ 

;ASCII name of command file to be detached 

COMNDS: .ASCIZ 

/R CKSTAT/<15><12> ;Start a monitoring program 

CMDEND: 



NER: .ASCIZ 

/?STRTDJ-F-Not enough room for command file./<7> 

NCA: .ASCIZ 

/?STRTDJ-F-No channels available for command file./<7> 

BADWRT: .ASCIZ 

/?STRTDJ-F-Error 

* writing command file./<7> 

BADDET: .ASCIZ 

/?STRTDJ-F-Error 

* starting detached job./<7> 

.END 

START 
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4.2.2.2 Aborting a detached job: This EMT may be used to abort a detached job. 
The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 2,132 
.WORD job-number 

where "job-number” is the job number of the detached job to be killed. If the 
job number is not valid for detached jobs, the carry flag will be set on return 
and the EMT error byte will be set to 1. 

Example: 


.TITLE CKABDJ 
.ENABL LC 


; Check 

status 

of a detached 


•MCALL 

.EXIT,.PRINT 

START: 

MOV 

//STATDJ, RO 


EMT 

375 


BCC 

1$ 


.PRINT 

.EXIT 

//NOTON 

1$: 

MOV 

#ABRTDJ,RO 


EMT 

375 


BCS 

ABERR 


.PRINT 

.EXIT 

//KILLED 



job and abort it if running 


;Point to EMT arg block to 
;Check status of a detached job 
;If still on, kill it 
;Else, say it isn't active 


;Point to EMT arg block to 
;Abort detached job 
;Since we checked, should never err 
;Say we killed it 


ABERR: 



.PRINT //ABERMS 
.EXIT 


STATDJ: 

.BYTE 


.WORD 

ABRTDJ: 

.BYTE 


.WORD 


.NLIST 

ABERMS: 

.ASCIZ 

NOTON: 

.ASCIZ 

KILLED: 

.ASCIZ 


1,132 

9. 


2,132 

9. 


;EMT arg value to check detached job status 
;Line number of detached job to be checked 
;EMT arg value to abort a detached job 
;Line number of detached job to be killed 


BEX 

/?CKABDJ-F-Invalid detached job number/<7> 
/?CKABDJ-I-No detached job on line #9/<7> 
/Detached job on line #9 killed./ 


.END START 
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4.2.2.3 Checking the status of a_ detached job: This EMT may be used to check 
the status of a detached job. The form of the EMT is: 


EMT 


375 


with RO pointing to the following argument block: 

.BYTE 1,132 
.WORD job-number 

where "job-number" is the number of the detached job to be checked. If the 

detached job is still active the EMT returns with the carry-flag cleared. If 

the detached job has terminated and the detached job line is free, the EMT 

returns with the carry-flag set. 

Example: 

See the example program CKABDJ in the previous section. 



o 
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5. DEVICE SPOOLING 


5.1 The concept of device spooling 

Device spooling is a technique that provides more efficient use of slow 
peripheral devices- Data sent to spooled devices is automatically redirected 
to a high speed disk file for temporary storage and sent to the slow device 
when it is ready to accept it. This allows a program generating data for the 
spooled device to continue processing without being slowed down by the 
peripheral. TSX-Plus optionally provides automatic spooling to output devices 
such as printers, card punches and plotters. Several devices may be spooled on 
a system. 

When a program directs output to a spooled device, the output is diverted by 
TSX-Plus to a spool disk data file. An entry is made in a spool file table 
indicating a spool file is ready for the spooled device. When the spooled 
device becomes free, the spool file is copied by TSX-Plus to the device. All 
of the processing is automatic and the user does not have to be concerned with 
its operation. In fact, a user can run programs without waiting for their 
output to be printed. Devices to be spooled must be declared when the system 
is generated. 

Spooled device handlers such as LP must be set to the ’’HANG" mode of operation 
to work properly with the TSX-Plus spooler. This can be done with the SET 
command. For example: 

.SET LP HANG 

Since the SET command actually stores this information permanently in the disk 
copy of the device handler, it need only be issued once. 

5.2 Directing output to spooled devices 

Output is directed to a spooled device in exactly the same way it would be 
directed to the device if it were not spooled. For example, if the line 
printer (LP) were spooled, the following commands would send a FORTRAN listing 
to the printer: 

.R FORTRA 
*TEST,LP:=TEST 

The name of a spooled device may be used in a MACRO .ENTER command just as a 
non-spooled device would. 

Any number of users may simultaneously write to a spooled device ^ithout 
conflict. TSX-Plus separates the output from each user and prints it\in an 
orderly fashion. A user may direct output through several I/O channels no the 
same or different spooled devices. i 

5.3 Operation of the spooler j 

The spooling system consists of a memory resident spool file control t:able 
which contains information concerning the user's spool file and a single system 


-89- 

























Device Spooling 

managed spool data disk file which contains the user's intercepted output. 
Every time a user opens an output channel to a spooled device, a new entry is 
created in the spool file control table. Output records directed through 
separate channels to the same device have separate entries in the spool file 
control table. Placement in this table is governed by the processing of the 
user's open request for the spooled device. 

The total number of spooled files that may be in existence is specified when 
TSX-Plus is generated. A spooled file is created when an I/O channel is opened 
to a spooled device; the file remains in existence until all of the output is 
processed by the spooled device. If a program opens a channel to a spooled 
device and the spool file control table already contains the maximum number of 
spooled files, the program is suspended until a slot becomes available in the 
spool file control table. 

All output directed to spooled devices is stored in a common disk data file. 
The total file space that is available for spooled data is specified when the 
TSX-Plus system is generated. Space within this disk file is dynamically 
allocated as needed on a block by block basis. Each block contains 508 bytes 
of user's output data. Therefore, write requests smaller than 508 bytes will 
be combined into one spool data block. A write request larger than 508 bytes 
will be split into more than one spool data blocks. If the spool data file is 
totally filled, programs writing to the spooled device will be suspended until 
space becomes available. 

Actual output to the spooled devices is processed on a sequential first- 
in/first-out basis. Since output is actually coming from the disk file, each 
I/O request to the device handler is the size of the spool data block (508 
bytes). While spooled files are being printed, TSX-Plus maintains a list of 
the blocks most recently printed. The length of this list is specified by the 
number of backup blocks declared during system generation. When the list 
becomes full, the oldest block is deallocated and the new block is added. When 
the entire spooled file has been successfully written, the entire list is 
deallocated. 

5.4 The SPOOL Command 

The SPOOL command is used to control the operation of the spooling system. The 
form of the SPOOL command is: 

SPOOL device,function,parameter 

where "device" is the name of a spooled device, "function" indicates the 
operation to be performed, and "parameter" is an optional item of information 
used with some functions. Each of the available functions is described below. 

The FORM and LOCK Functions 

The FORM and LOCK functions are used to specify the name of the currently 
mounted form. The form name is specified in the "parameter" field of the 
command. The FORM function allows TSX-Plus to request a form mount when a 
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different form is needed. The LOCK function specifies that the form is to be 
locked on the printer and disables form mount request messages. 

Examples: 


.SPOOL LP,FORM,BILLS 
.SPOOL LP,LOCK,BILLS 
. SPOOL LP,FORM,STD 

Note the difference between the FORM keyboard command and the SPOOL command 
with the FORM or LOCK functions. The FORM command is used by the TSX-Plus user 
to specify the default form name to be used for subsequent spool files. The 
SPOOL FORM/LOCK commands are used by the TSX-Plus operator to tell the spooling 
system which form is currently mounted. 

The ALIGN Function 

The ALIGN function is used to print a form alignment file on a spooled device. 
The name of the alignment file is specified in the "parameter*’ field of the 
command. The default file extension for form alignment files is "ALN". 

Examples: 

.SPOOL LP,ALIGN,BILLS 
.SPOOL LP,ALIGN,RK1:PAYROL.DAT 
.SPOOL LP,ALIGN,DX;RP0RT2 


The DELETE Function 

The DELETE function is used to abort printing of the file currently being 
printed on the indicated spooled device. The spooler waits for the most recent 
I/O request to complete before deallocating all disk data blocks associated 
with the deleted spool file. The DEL function has no effect if no file is 
currently being printed. 

Examples: 

.SPOOL LP,DELETE 
.SPOOL LS,DELETE 


The SKIP Function 

The SKIP function causes the spooler to skip over the next n. blocks in the 
spool file that is currently being printed, where n. is specified in the 
parameter field of the instruction. Each block in the spool data file contains 
508. characters. Printing of the file continues after the indicated number of 
blocks have been skipped. 
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Examples: 

.SPOOL LP,SKIP,10 
. SPOOL LP,SKIP > 100 

The BACK Function 

The BACK function causes the spooler to skip backward in the spool file a 
number of blocks and then resume printing at that point. The number of blocks 
involved is specified when TSX-Plus is generated. Each block in the spool data 
file contains 508. characters. This function is particularly useful for 
recovering from paper tears or remounts. The spooler will finish printing the 
current block before backing up. 

Examples: 


.SPOOL LP,BACK 
. SPOOL LS,BACK 

The STAT Function 

The STAT function is used to determine the status of a spooled device. 
Information returned includes: the condition of the spooler (active, idle, or 
waiting for a form mount); the name of the currently mounted form; and 
information about files waiting to be printed on the device. The SHOW QUEUE 
command may also be used to display information about files in the spooler 
queue. 

Example: 


. SPOOL LP,STAT 
Spooler idle 

Currently mounted form = STD 
No files in queue 

The SING and MULT Functions 

The SING and MULT functions control how the spooler will handle multiple files 
queued for the same form. In "MULT" mode (the initial setting) no form mount 
request message is generated if a spool file is found that needs the currently 
mounted form. Processing of the file begins automatically. 

In "SING" mode a form mount request is generated for every file even if the 
file needs the currently mounted form. This is useful where equipment setup or 
form alignment is needed for every file. 

Examples: 

.SPOOL LP,SING 
♦ SPOOL LP,MULT 
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The HOLD and NOHOLD Functions 

A spooled device that is in the HOLD mode will not begin to process a spool 
file until the file is completely created and the I/O channel associated with 
the file is closed. A spooled device that is in NOHOLD mode will begin to 
process a spool file as the file is being created. In NOHOLD mode, the spooler 
will begin to process a file sooner; however, if the file is being created 
slowly, the spooled device will remain busy (and unavailable to other users) 
for as long as it takes to finish generating the file. If the spool storage 
file is completely filled, the spooler will attempt to free space by beginning 
to process open spool files even if HOLD is in effect. 

The default [NO]HOLD mode is established when the TSX-Plus system is generated. 
A [NO]HOLD command remains in effect until another [NO]HOLD command is issued 
or the system is restarted. 

Examples: 

.SPOOL LP,NOHOLD 
. SPOOL LP,HOLD 

It is also possible to dynamically request that a file being printed through 
the spooler be either held until the file is closed or begin printing as data 
is made available from the program. This could be used in a situation where 
NOHOLD is the normal condition, but a program which uses the printer generates 
data slowly. If data were passed to the printer as soon as available, then 
printer output from all other jobs would be delayed until the slow job closes 
the output. This can be avoided by the having the slow program select hold 
mode for its output. Then, other jobs can proceed to use the printer without 
being delayed by the slow job. The form of the EMT to select hold or nohold 
mode on an individual file basis is: 

EMT 375 

with RO pointing to the following argument block: 

•BYTE chan,151 
.WORD 0 
.WORD flag 

where "chan” is the channel number which has been used to open the print file 
and "flag" indicates whether the file is to be printed as it is generated or 
held until the file is closed. If "flag"=0, the output is printed as generated 
(equivalent to NOHOLD); if "flag"=l, then the output is not printed until the 
file is closed. This EMT must be issued after a channel has been opened to the 
printer (through the spooler), but before any data has been written to it. If 
the channel is open to any non-spooled device, then the EMT is ignored. 


- 93 - 
















Device Spooling 
Example: 

.TITLE SPHOLD 
.ENABL LC 


Demonstrate the EMT to hold spooler output until the file is closed 



•MCALL 

.CSISPC,.LOOKUP,.READW, 

.WRITW,.CLOSE,.EXIT 

ERRBYT 

= 52 


;EMT error code byte location 

START: 

.CSISPC 

//OUTSPC, //DEFEXT, #0 

;Get name of file to copy 


BCS 

START 

;Proceed unless error 


MOV 

^INSPC,R1 

;Point to first input filspc 

OPNFIL: 

.LOOKUP 

//AREA, //0,R1 

;Try to open input file 


BCS 

START 

;Get a new command on error 


MOV 

//OUTSPC, R2 

;Point to output filspc 


MOV 

//~RLP ,(R2)+ 

;Put LP: in output filspc 


ADD 

#2, R1 

;Point to input filspc filename 


MOV 

(R1)+,(R2)+ 

;Move file name into LP filspc 


MOV 

(R1)+,(R2)+ 

; (not necessary, but convenient) 


TST 

(Rl)+ 

;Skip over file extension 


.LOOKUP 

//AREA, #1, //OUTSPC 

;0pen channel to printer (spooled) 


BCC 

NOHOLD 

;Proceed unless error 

GIVEUP: 

.CLOSE 

#0 

;Close input file 


.EXIT 


;And give up 

; Tell 

spooler 

to hold file until it is 

closed 

; (must 

be issued before any writes to 

file) 

NOHOLD: 

MOV 

//SPHOLD, RO 

;Point to EMT arg block to 


EMT 

375 

;Hold output until close 


CLR 

R2 

;Initialize block pointer 

6$: 

.READW 

//AREA, #0, //BUFFER, #256., 

R2 ;Copy a block from the file 


BCS 

NXTFIL 

;Try next file on error 


.WRITW 

//AREA, #1, //BUFFER, #256., 

#0 ;Copy the file block to LP 


BCC 

8$ 

;Error? 


.CLOSE 

//I 

;Close print file 


BR 

GIVEUP 

;Forget it 

8$: 

INC 

R2 

;Point to next block 


BR 

6$ 

;And get next block 

NXTFIL: 

.CLOSE 

#0 

;Close input file 


.CLOSE 

//I 

;and print file 


TST 

2(Rl) 

;Any input file? 


BNE 

OPNFIL 

;Repeat if so 


BR 

START 

;Else ask for more files 

AREA: 

.BLKW 

10 

;General EMT arg block area 

SPHOLD: 

.BYTE 

1,151 

;EMT arg block to hold spool output 


.WORD 

0 

;on channel 1 until file is closed 

HNH: 

.WORD 

1 

;HNH=0 immed; HNH=1 hold til close 

OUTSPC: 

.BLKW 

15. 

;0utput file specs 
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INSPC: 

• BLKW 

CM 

;Input file 

specs 

DEFEXT: 

.WORD 

0,0,0,0 

;No default 

file types 

BUFFER: 

.BLKW 

256. 

;I/0 buffer 

area 


.END 

START 




5.5 Use of special forms with spooled devices 

Output files directed to spooled devices are queued and held until the spooled 
device becomes free. Because of this, a special procedure is required to 
synchronize the mounting of a special form with the printing of a file that 
requires the form. 

If the first character in a file directed to a spooled device is a right square 
bracket ("]’’), TSX-Plus will interpret the following one to six characters in 
the file as the name of the form on which the file should be printed. Form 
names may be from one to six characters in length and must be specified 
immediately following the initial square bracket character. The form name must 
be terminated with a carriage return, line feed. Square bracket characters are 
not significant to the spooler in any position other than the first character 
of the file. 

If a spooled file does not begin with a right square bracket character, 
TSX-Plus uses the form name that was last specified by the user with a FORM 
command (see Chapter 2). If no FORM command has been issued by the user, 
TSX-Plus uses the form name ”STD M for the file. 

Each time TSX-Plus selects a file to be printed on a spooled device, it first 
looks for a waiting file that requires the form currently mounted on the 
spooled device. If several such files are available, the oldest one is 
started. If no file can be found that requires the currently mounted form, 
TSX-Plus selects the oldest file requiring a different form and issues a form 
mount request. The message appears on the the operator s terminal as: 

’’Mount 'XXXXXX' form on dd” 

where ’’XXXXXX’’ represents the form name and "dd” is the spooled device. The 
terminal to which the message is directed is the one declared as the operator s 
console when the TSX-Plus system was generated. 

Once the form mount request message is sent, the spooler for the device 
requiring the new form is suspended. In order to restart the spooler the 
operator must issue a SPOOL-FORM or SPOOL-LOCK command. These commands tell 
the spooler that a particular form has been mounted and is ready for use. The 
operator does not have to mount the form called for in the form mount request. 
He may mount any form he desires, in which case TSX-Plus will search for a 
spool file that needs the form actually mounted. 

The SPOOL-FORM and SPOOL-LOCK commands are both used by the operator to 
indicate which form has been mounted; however, there is a difference in the 
effect of the two commands. After processing all files that need the currently 
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mounted form, TSX-Plus checks for files requiring a different form. If there 
are any, it checks to see if the current form was mounted using a SPOOL-FORM or 
SPOOL-LOCK command. If a SPOOL-FORM command was used, TSX-Plus issues a form 
mount request message. If a SPOOL-LOCK command was used, TSX-Plus considers 
the current form to be locked on the printer and does not issue a form mount 
message; rather, it waits for new spool files to be created that need the 
currently mounted form. 

5.6 Form alignment procedure 

When mounting a new form it is usually necessary to verify the correct 
positioning of the form before starting production printing on the form. The 
SPOOL-ALIGN command provides this facility. 

The SPOOL-ALIGN command allows the TSX-Plus operator to specify a form 
alignment file to be printed on the indicated spooled device. Form alignment 
files are printed immediately without regard to the name of the currently 
mounted form. The SPOOL-ALIGN command may be issued repeatedly if several 
attempts are required to mount a form. 

Alignment files are created by the user and may contain any desired infor¬ 
mation. Typically they contain a short sample output file that matches a 
particular form. Alignment files should not contain a form name specification. 
The normal sequence of operations involving a form mount is as follows: 

1. TSX-Plus issues a form-mount request message and suspends the 
spooler. 

2. The operator mounts the desired form and issues one or more SPOOL- 
ALIGN commands to verify its positioning. 

3. Once the form is correctly positioned, the operator issues a 
SPOOL-FORM or SPOOL-LOCK command to tell TSX-Plus which form has been 
mounted. 

4. TSX-Plus begins printing the oldest file that needs the currently 
mounted form. 

The SPOOL-ALIGN command may be issued at any time, but it is typically used 
between a form—mount message and a SPOOL—FORM or SPOOL—LOCK command. 











6. PROGRAM CONTROLLED TERMINAL OPTIONS 


6.1 Terminal input/output handling 

The terminal keyboard and screen provide the principal interface between a 
time-sharing user and the TSX-Plus operating system. TSX-Plus accepts 
characters from the keyboard, echoes them to the screen, and stores them in a 
separate buffer for each time-sharing user. Then, when a program (either a 
user written program, or a utility, or the operating system keyboard monitor) 
requests input from the terminal, characters are removed from the internal 
buffer and passed to the program. The low-level requests for input from a 
program can call for a single character (.TTYIN), or for an entire line 
(.GTLIN, .CSIGEN, .CSISPC), or for a whole block of characters (.READ). Since 
the requests for a whole line of input are most common, TSX-Plus improves 
overall efficiency for many users by retaining characters typed at the keyboard 
in an internal buffer until a special character is typed which indicates that 
the line of input is complete. This special character, which indicates that 
keyboard input is ready, is called an activation character . The standard 
activation characters are carriage return and line feed. In addition, several 
control keys will also cause immediate system response. For example, control-C 
is used to abort the execution of a running program. If the program is waiting 
for input, one control-C will cause an immediate abort. If the program is not 
waiting for input, it is necessary to type two control-C's to get the system's 
attention and abort a program. 

When a program requests terminal input, TSX-Plus puts the program in a 
suspended state until an activation character is typed. This state, in which a 
program is waiting for input, but no activation character has been typed, is 
identified as the TI state by the SYSTAT command. When characters are typed at 
the terminal, TSX-Plus responds quickly and stores them in the terminal input 
buffer for that line, then returns to process other jobs which need its 
attention. Thus, the amount of time the CPU spends processing input characters 
is kept to a minimum, and the amount of CPU time used by a program in the TI 
state is also very small. Some programs, however, request single characters 
with the .TTYIN request. Normally, these programs are treated by TSX-Plus just 
as those requesting lines of input (e.g. .GTLIN requests). That is, the job 
is suspended, input characters are stored in the terminal input buffer, and 
characters are only passed to the program after an activation character is 
typed. If a program requests a character with a single .TTYIN, the user can 
type as many characters as the terminal input buffer will hold (allocated 
during system generation), but the program will remain suspended and no 
characters are passed to the program. Then, when an activation is typed, the 
program is restored to an active state, the first character in the input buffer 
is passed to the program and processing continues. If the program requested no 
more characters, then on exit the remainder of the input buffer, including the 
activation character, would be passed to the next program (usually the keyboard 
monitor) which would try to interpret them. This may result in an invalid 
command error message. 

TSX-Plus allows the programmer a wide variety of ways to influence the normal 
input scheme outlined above. One of the most common is the use of single 
character activation". With this technique, all characters are regarded as 
activation characters. That is, if a program requests a single character with 
a .TTYIN, then as soon as a character is typed and becomes available in the 
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input buffer, it is passed to the program and the program resumes execution. 
The standard way to request single character activation under RT-11 is by 
setting bit 12 in the user's Job Status Word (JSW). However, under TSX-Plus, 
this is not by itself sufficient to cause single character activation. The 
reason is that quite a few programs designed for a single user environment use 
this in a way that causes constant looping back and consequently "burns up a 
large amount of processor time. In a single user environment, this is of minor 
importance since no other jobs are trying to use the processor at the same 
time. Of course, in a multi-user system, this is wasteful and should be 
avoided. Therefore, under TSX-Plus, setting JSW bit 12 is not by itself 
sufficient to initiate single character activation. It is necessary BOTH to 
set bit 12 and to issue a special command to TSX—Plus indicating that single 
character activation is actually desired. This may be done either by speci¬ 
fying single character activation when running the program (see the /SINGLECHAR 
switch described under the R command), or with the SET TT SINGLE command, or 
with the ”S" program controlled terminal option described in this chapter. 


The situation in which a program requests single characters but none are 
available in the input buffer also receives special treatment. The single 
character input request is eventually coded as EMT 340. The .TTYIN request 
repeats this request until a character is finally obtained, whereas the .TTINR 
request supposedly permits processing to continue if no character is available. 
In fact, however, the EMT 340 call will itself suspend the job until a 
character is available from the input buffer. This is referred to as 
"stalling" on a .TTYIN. The purpose is to avoid the unnecessary looping back 
to get a character. Under RT-11, if the programmer decides not to wait for a 
character to become available, but rather proceed with execution, it is only 
necessary to set bit 6 (100 octal) in the Job Status Word. Again, some 
programs abuse this technique and would waste the system resources in a 
time—sharing environment. So, TSX—Plus requires confirmation that the user is 
aware of the extra system load that could be caused by the constant looping 
back checking for a character. This may be done either as a system command 
(SET TT NOWAIT), or with the /SINGLECHAR switch when running the ^program, or 
within a program by using the program controlled terminal option U .. All of 
these methods cause TSX-Plus to honor bit 6 in the JSW. If nowait input is 
truly desired under TSX-Plus, it is necessary BOTH to set bit 6 in the JSW and 
to tell TSX-Plus to use nowait input (R[UN] /SINGLECHAR, or SET TT NOWAIT, or 
the "U" terminal option). 


TSX-Plus allows many other ways of modifying terminal input and output for 
special circumstances. These are provided to allow maximum versatility in the 
system while still maintaining the high efficiency needed in a multi-user 
environment. The programmer communicates the need for special terminal 
handling to the system through the use of special "program controlled terminal 
options". These are described individually in the next section. 
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6.2 Program controlled terminal options 

The following table lists the functions which may be modified during program 
execution. 


Function 

Character Meaning 


Set rubout filler character. 

Enable VT52 & VT100 escape-letter activation. 
Disable VT52 & VT100 escape-letter activation. 
Define new activation character. 

Turn on character echoing. 

Turn off character echoing. 

Disable virtual lines. 

Enable lower case input. 

Disable lower case input. 

Enable deferred character echo mode. 

Disable deferred character echo mode. 

Set transparency mode for output. 

Suspend command file input. 

Restart command file input. 

Reset activation character. 

Set activation on field width. 

Turn on high-efficiency TTY mode. 

Turn on single-character activation mode. 

Turn off single-character activation mode. 
Enable no-wait TT input test. 

Set field width limit. 

Turn tape mode on 
Turn tape mode off 

Disable echo of line-feed after carriage-return 
Enable echo of line-feed after carriage-return 


A 

B 

C 

D 

E 

F 

H 

I 

J 

K 

L 

M 

N 

0 

P 


Q 

R 

S 

T 

U 

V 

w 

X 

Y 
Z 


These functions have a temporary effect in that they are automatically reset to 
their normal values when a program exits to the keyboard monitor. They are not 
reset if the program chains to another program until control is finally 
returned to the monitor. Some terminal options (notably high-efficiency and 
single-character modes) are incompatible with and override some other terminal 
options. 

TSX-Plus provides two methods for a running program to dynamically alter some 
of the parameter settings relating to the user's timesharing line. The 
preferred method of selecting these functions is to use the TSX-Plus EMT for 
that purpose. This is readily available from MACRO programs and an appropriate 
MACRO subroutine should be linked into jobs written in other languages. The 
form of the EMT to select program controlled terminal options is: 


EMT 


375 
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with RO pointing to the following argument block: 

.BYTE 0,152 

.WORD function-code 

.WORD argument-value 

where "function-code" is the character from the table above which selects the 
terminal option, and "argument-value" may be a third value used only with some 
of the functions. An advantage of the EMT method of selecting program 
controlled terminal options is that they may be used even when the terminal is 
in high-efficiency mode. 

Example: 


.TITLE EMTMTH 
.ENABL LC 


Demonstrate TSX-Plus program controlled terminal options using 
the EMT method. 

.MCALL .GVAL,.PRINT,.EXIT,.TTYIN 
.GLOBL PRTDEC 


; Determine and display current 
; Default = 35, but don't count 

START: . GVAL //AREA, #-4. 

MOV R0,R1 

.PRINT //LEAD IS 

MOV R1,R0 

CALL PRTDEC 

. PRINT //LEADND 


lead-in char 
on it 

;Determine current leadin character 
;Save it 

;"Current lead-in is" 

;Retrieve lead-in char value 
;Display it 


Set rubout filler character 

MOV //SETRUB ,R0 

EMT 375 


;Point to EMT arg block to 
;Set rubout filler character 


Now demonstrate the current rubout filler character 
Back «pace is the default, which we changed to underline 


.PRINT //TRYIT 
MOV //BUFFER, Rl 

1$: .TTYIN 

CMPB R0,//12 

BEQ 2$ 

CMP Rl, //BUFEND 

BLO 1$ 


;"Enter some and delete them" 

;Point to input buffer 

;Get next char into input buffer 

;End of input (CR/LF pair)? 

;Yes, terminate input 
;Buffer overflow? 

;Get more if not 


2$: .PRINT //THANKS 
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.EXIT 

AREA: .BLKW 

10 

;General EMT arg block 

SETRUB: .BYTE 

0,152 

;EMT arg block to 

.WORD 

'A 

;Set rubout filler character 

.WORD 

* 

; to underline 

TRYIT: .ASCII 

/Enter 

some characters at the prompt and then / 

.ASCII 

/erase 

them with/<15><12>/DELETE or Control-U./ 

.ASCII 

/ They 

should be replaced with underlines./<15><12>/*/<200> 

LEADIS: .ASCII 

/We don't care that the current lead-in char is /<200> 

LEAJDND: .ASCIZ 

/./ 


THANKS: .ASCIZ 

<15X12>/STOP -- Thank you./ 

BUFFER: .BLKB 

81. 


BUFEND: 

.END 

START 



When it is not practical to incorporate the EMT method of selecting program 
controlled terminal options into a program, an alternate method using a 
"lead-in" character may be used. This is conveniently done by sending a 
sequence of characters to the terminal using the normal terminal output 
operations of the language. Examples are the FORTRAN TYPE, COBOL—Plus DISPLAY, 
BASIC PRINT, and Pascal WRITE statements. Program controlled terminal options 
are selected by having the running program send the lead-in character immedi¬ 
ately followed by the function character and for some functions a third 
character defining the argument value for the function. TSX-Plus intercepts 
the lead-in character and the one or two following characters and sets the 
appropriate terminal option. It does not pass these intercepted characters 
through to the terminal. The default value for the lead-in character is the 
ASCII GS character (octal value 35; decimal value 29). However, the lead-in 
character may be redefined during system generation when the value conflicts 
with other uses of the system. For example, some graphics terminals use the GS 
character as either a command or parameter value. Programmers should not rely 
on the default value of the lead-in character, but may obtain the current value 
of the lead-in character from the .GVAL request with an offset of -4. Note 
that when in high-efficiency mode (set with either the RUN/HIGH switch or the 
”R" program controlled terminal option) output character checking is disabled 
and the lead-in character method of selecting program controlled terminal 
options is disabled; in this case, the lead-in character, function-code 
character, and argument value character are passed through to the terminal. 
When in high-efficiency mode, the EMT method of selecting program controlled 
terminal options is still functional. See Chapter 7 for information on turning 
high-efficiency terminal mode off by means of an EMT. 

Example; 

PROGRAM LEADIN 
C 

C Demonstrate TSX-Plus program controlled terminal options using 
C the "lead-in" character method. 

C 
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BYTE LEADIN(2) 

INTEGER ILEAD 

EQUIVALENCE (ILEAD.LEADIN(l)) 

C 

C Determine and display current lead-in char 
C Default = 29, but don't count on it 

I LEAD = ISPY(-4) S.GVAL with offset = -4. 

TYPE 820,LEADIN(1) !Display the current lead-in char value 

Set rubout filler character 

TYPE 800,LEADIN(1),'A','_' 

Now demonstrate the current rubout filler character 
Back space is the default, which we changed to underline 

TYPE 810 !Ask for something to be erased 

ACCEPT 830 !Wait for input before exiting 

C 

STOP 'Thank you.' 

800 FORMAT(1H+,A1,$) 

810 F0RMAT(1H0,'Enter some characters at the prompt and then ', 

1 'erase them with'/' DELETE or Control-U.',^ 

1 ' They should be replaced with underlines. /*,$) 

820 FORMAT(' The current value of the lead-in character is ,13, . ) 
830 FORMAT(4OH ) 

END 


The following paragraphs explain the uses of each of the program controlled 
terminal option function-codes. Any of these options may be selected by either 
the EMT method or by the lead-in character method. 

6.2.1 "A” function—Set rubout filler character. 

When a scope type terminal is being used, the normal response of TSX-Plus to a 
DELETE character is to echo backspace-space-backspace which replaces the last 
character typed with a space. TSX-Plus responds to a CTRL-U character in a 
similar fashion, echoing a series of backspaces and spaces. Some programs that 
display forms use underscores or periods to indicate the fields where the user 
may enter values. In this case it is desirable for TSX-Plus to echo backspace- 
character-backspace for DELETE and CTRL-U where "character" may be period or 
underscore as used in the form. The character to use as a rubout filler is 
specified by the argument-value with the EMT method or by the third character 
with the lead-in character method. 

6.2.2 "B" & "C" functions—Set VT52 & VT100 escape-letter activation. 

VJ52 and IfTlOO terminals are equipped with a set of special function keys 
marked with arrows and other symbols. When pressed, they transmit two or three 
character escape sequences. The "B” function tells TSX-Plus to consider these 
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as activation sequences. The escape character and the letter are not echoed to 
the terminal, but are passed to the user program. The "C" function disables 
this processing and causes escape to be treated as a normal character (initial 
setting). 

6.2.3 "D" function—Def ine new activation character. 

Under normal circumstances TSX-Plus only schedules a job for execution and 
passes it a line of input when an "activation” character such as carriage 
return is received. The "D” function provides the user with the ability to 
define a set of activation characters in addition to carriage return. 

The new activation character is specified by the argument-value with the EMT 
method or by the third character with the lead—in character method. . The 
maximum number of activation characters that a program may define is specified 
when the TSX-Plus system is generated. 

Using this technique, any character may be defined as an activation character, 
including such characters as letters, DELETE, CTRL-U, and CTRL-C. ^ When a 
user-defined activation character is received, it is not echoed but is placed 
in the user^s input buffer which is then passed to the running program. 

By specifying CTRL-C as an activation character, a program may lock itself to a 
terminal in such a fashion that the user may not break out of the program in an 
uncontrolled manner. 

If carriage return is specified as a user activation character, neither it nor 
a following line feed will be echoed to the terminal. TSX-Plus will also not 
add a line feed to the input passed to the program. 

6.2.4 "E” and "F" functions—Control character echoing. 

The "E" and "F" functions are used to turn on and off character echoing. The 
"E" function turns it on, and the "F" function turns it off. An example of a 
possible use is to turn off echoing while a password is being entered. 

6.2.5 "H” funct ion—Disable virtual line use. 

The "H" function disables the virtual line facility for the time-sharing line. 

6.2.6 ”1" and "J" functions—Control lower case input. 

The'""I" - function allows lower case characters to be passed to the running 
program. The "J" function causes TSX-Plus to translate lower case letters to 
upper case letters. The SET TT [NO]LC keyboard command also performs these 

functions. 

6.2.7 "K” and "L" functions—Control character echoing. 

The "K” - function causes TSX-Plus to enter "deferred" character echo mode. The 
"L" function causes TSX-Plus to enter immediate character echo mode. Any 
characters in the input buffer which have not been echoed when the "L” function 
is selected will be immediately echoed. See the description of the SET TT 
[NO]DEFER command for an explanation of deferred echo mode. 
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6.2.8 "M" function—Set transparency mode of o utput. 

If transparency mode is set, TSX-Plus will pass through each transmitted 
character without performing any special checking or processing. Transparency 
mode allows the user's program to send any 7-bit character to the terminal. 
Note that once transparency mode is set on, TSX-Plus will no longer recognize 
the lead-in character (octal 35, which means a program control function 
follows). The only way to turn off transparency mode is to exit to KMON. 

6.2.9 "N" and "0" Functions—Control command file input. 

When - a - command file is being used to run programs (see Chapter 3), input which 
would normally come from the user's terminal is instead drawn from the command 
file. Occasionally, it is desirable to allow a program running from a command 
file to accept input from the user's terminal rather than the command file. 
The "N” function suspends input from the command file so that subsequent input 
operations will be diverted to the terminal. The ”0" function redirects input 
to the command file. These functions are ignored by TSX-Plus if the program is 
not being run from a command file. 

6.2.10 M P" functio n—Reset activation character. 

The "P" function performs the complement operation to the "D function. The 
"P" function is used to remove an activation character that was previously 
defined by the "D" function. The character to be removed from the activation 
character list is defined by the argument-value with the EMT method or by the 
third character with the lead-in character method. 

Only activation characters that were previously defined by the "D" function may 
be removed by the "P" function. 


6.2.11 "Q” function—Set activation on fi eld width. 

The "Q" function allows the user to define the width of an input field so that 
activation will occur if the user types in as many characters as the field 
width, even if no activation character is entered. The field width is 
specified by the ASCII code value of the argument-value with the EMT method or 
of the third character with the lead-in character method. If-an activation 
character is entered before the field is filled, the program will be activated 
as usual. Each time activation occurs the field width is reset and must be set 
again for the next field by reissuing the "Q" function. For example, the 
following sequence of characters could be sent to TSX-Plus to establish a field 
width of 43 characters: "<lead-in>Q+”. Note that the character + has the 
ASCII code of 053 (octal) which is 43 decimal. 


6.2.12 "R" functi on—Turn on high-efficiency terminal mode^ 

The "R” function causes TSX-Plus to place the line in "high efficiency 
terminal mode. The effect of this is to disable most of the character testing 
overhead that is done by TSX-Plus as characters are transmitted and received by 
the line. Before entering high-efficiency mode the program must declare a 
user-defined activation character that will signal the end of an input record. 
Once a program has entered high-efficiency mode, characters sent to the 
terminal are processed with minimum system overhead. For example, tab 
characters are not expanded to spaces. Also, TSX-Plus does not check to see i 
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the character being sent is the TSX-Plus terminal control "leadin'’ character. 
This means that the lead-in character method may not be used to control 
terminal options until the program exits or the EMT to turn off high efficiency 
mode is used (see Chapter 7). Characters received from the terminal are passed 
to the program with minimum processing: they are not echoed; and control 
characters such as DELETE, control-U, control-C, control-W and carriage-return 
are all treated as ordinary characters and passed directly to the program. 
High-efficiency mode terminal I/O is designed to facilitate machine-to-machine 
communication; it is also useful for dealing with buffered terminals that 
transmit a page of information at a time. 

6.2.13 ”S" function—Turn on s ingle-character activation mode. 

The ^S" function causes TSX-Plus to allow a program to do single-character 
activation by setting bit 12 in the Job Status Word. Normally TSX-Plus stores 
characters received from the terminal and only activates the program and passes 
the characters to it when an activation character, such as carriage-return, is 
received. It does this even if bit 12 is set in the Job Status Word, which 
under RT-11 causes the program to be passed characters one-by-one as they are 
received from the terminal. The "S" function can be used to cause TSX—Plus to 
honor bit 12 in the Job Status Word. If JSW bit 12 is set and the program is 
in single-character activation mode, TSX-Plus passes characters one-by-one to 
the program as they are received and does not echo the characters to the 
terminal. The /SINGLECHAR switch for the R[UN] command and the SET TT SINGLE 
command can also be used to cause TSX—Plus to honor JSW bit 12. Since the 
high-efficiency mode implies certain terminal characteristics (such as buffered 
input and no echo), it is not possible to override these inherent modes by 

using other function codes. 

6.2.14 "T" function—Turn off single-character activation mode. 

The "T" function is the complement of the S function. It turns off single 
character activation mode. 

6.2.15 "U" function—Enable non-w ait TT input testing. 

The "U" function causes TSX-Plus to allow a program to do a .TTINR EMT that 
will return with the carry bit set if no terminal input is pending. Normally 
TSX-Plus suspends the execution of a program if it attempts to obtain a 
terminal character by doing a .TTINR EMT and no input characters are available. 
It does this even if bit 6 of the Job Status Word is set, which under RT 11 
would enable non-blocking .TTINR's. This is done to prevent programs from 

burning up CPU time by constantly looping back to see if terminal input is 

available. The "U" function causes TSX-Plus to honor bit 6 in the Job Status 
Word and allows a program to do a .TTINR to check for pending TT input without 
blocking if none is available. The SET TT NOWAIT command and the /SINGLECHAR 
switch for the R[UN] command also perform this function. Because the single 
character terminal option determines several terminal operating modes (such as 
no echo and transparent input), it is incompatible with other terminal 

functions which would conflict with the implied single—character operation. 
See the description of special terminal mode in the RT-11 Programmer s 
Reference Manual. 
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6.2.16 "V" function—Set field width limit. 


The "V” function is used to set a limit on the number of characters that can be 
entered in the next terminal input field. Once the "V" function is used to set 
a field limit, if the user types in more characters to the field than the 
specified limit, the excess characters are discarded and the bell is rung 
rather than echoing the characters. An activation character still must be 
entered to complete the input. The field width is specified by the ASCII code 
value of the argument-value with the EMT method or of the third character with 
the lead-in character method. The field size limit is automatically reset 
after each field is accepted and must be re-specified for each field to which a 
limit is to be applied. Note the difference between the "Q" and "V" functions. 
The "Q" function sets a field size which causes automatic activation when the 
field is filled; the "V" function sets a field size which causes characters to 
be discarded if they exceed the field size. 

6.2.17 "W" and "X" functions—Control tape mode. 

The ”W” function turns on "tape” mode and the "X" function turns it off. 
|"Tape" mode can be used when a line is connected to a paper tape, cassette 
rape, floppy disk or other device that responds to X-ON/X-OFF characters to 
start and stop transmission. Turning on tape mode has three effects: 

1) TSX-Plus sends an X-OFF character (CTRL-S) to the terminal when the terminal 
input buffer fills to the point that only 10 free character positions remain; 

2) TSX-Plus sends an X-ON character (CTRL-Q) to the terminal when a program 
begins waiting for input from the line and an X—OFF has been sent previously; 

3) line-feed characters are ignored unless line-feed is declared to be a 
user—defined activation character — this is done so that each line of input 
may be terminated by both a carriage-return and a line-feed. The SET TT 
[NOJTAPE keyboard command may also be used to control tape mode. 

6.2.18 "Y" and "Z" functions —Control line-feed echo. 

The "Y" function is used to disable the echoing of a line-feed character when a 
carriage-return is received. Normally, when TSX-Plus receives a carriage- 
return character, it echoes carriage-return and line-feed characters to the 
terminal and passes carriage-return and line-feed characters to the program. 
The "Y” function alters this behavior so that it only echoes carriage-return 
but still passes both carriage-return and line-feed to the program. This 
^function can be used to advantage with programs that do cursor positioning and 
'which do not want line-feed echoed because it might cause the screen display to 
scroll up a line. The "Z" function restores the line-feed echoing to its 
normal mode. 
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7. TSX-Plus EMT'S 


TSX-Plus provides several system service calls (EMTs) in addition to those 
compatible with RT-11. In order to take advantage of the special features of 
TSX—Plus, programs written to run under both TSX-Plus and RT-11 should check to 
see if they are under TSX-Plus. This chapter describes the preferred method of 
checking and goes on to describe several of the special EMTs provided by 
TSX-Plus. EMTs which relate specifically to features described elsewhere in 
this manual are included in the appropriate chapters. 

7.1 Determining if a job is running under TSX-Plus 

In cooperation with Digital Equipment Corporation, a bit has been allocated in 
the RT—11 sysgen options word at fixed offset 372 into the RMON. The high 
order bit (bit 15; mask 100000) of this word will be set (1) if the current 
monitor is TSX-Plus version 5.0 or later. This bit will be clear if the 
monitor is any version of RT-11. Testing this bit is the preferred method of 
determining if a job is running under TSX-Plus. However, if a program is 
expected to also be used under older versions of TSX—Plus, then an alternative 
method is necessary. For older versions of TSX-Plus, first issue the .SERR 
request to trap invalid EMT requests and then issue the TSX-Plus EMT to 
determine the time-sharing line number. If the job is running under RT-11, 
this EMT will be invalid and the carry bit (indicating an error) will be set on 
return. If the job is running under TSX-Plus, then the EMT will return without 
error and the line number will be in R0. 

Example: 


.TITLE TSXENV 
.ENABL LC 


Demonstrate preferred method of determining whether job is 
running under TSX—Plus or RT—11 


.MCALL .PRINT,.EXIT,.SERR,.HERR 


JSW 

= 44 

;Job Status Word 

address 

RMON 

= 54 

;Pointer to base 

of RMON 

SYSGEN 

= 372 

;Index into RMON 

for sysgen features 

START: 

• PRINT (/UNDER 

;"Running under" 



This is the preferred method, but will not work prior to 
TSX-Plus version 5.0 


MOV RM0N,R1 
TST SYSGEN(Rl) 

BPL RTll 


;Point to base of RMON 

;See if running under TSX-Plus 

;Branch if running under RT-11 


This is the old method, but will work correctly with 
all versions of TSX-Plus 

•SERR ;Trap invalid EMT error 
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9 

MOV 

//TSXLN, RO 

;Point to EMT arg block to 

9 

EMT 

375 

;Determine TSX-Plus line number 

9 

BCS 

RT11 

;Branch if running under RT-11 

9 

.PRINT 

.EXIT 

//TSXPLS 

; ’'TSX-Plus*' 

RT11: 

.HERR 


;Reset SERR trap 


.PRINT 

.EXIT 

#NOTPLS 

;"RT-11 M 

TSXLN: 

.BYTE 

0,110 

;EMT arg block to get line number 



.NLIST 

BEX 

UNDER: 

.ASCII 

/Monitor is /<200> 

TSXPLS: 

.ASCIZ 

/TSX-Plus./ 

NOTPLS: 

.ASCIZ 

/RT-11./ 


.END 

START 

7.2 Determining 

the TSX-Plus line number 


The following EMT will return in RO the number of the line to which the job is 
attached. Physical lines are numbered consecutively starting at 1 in the same 
order as specified when TSX-Plus is generated. Detached job lines occur next 
and virtual lines are numbered last. 

The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,110 


Example: 

.TITLE LNTT 
.ENABL LG 


; What TSX line number is this terminal attached to? 
; And what type terminal does TSX-Plus think it is? 


.MCALL 

•PRINT,.EXIT, 

.TTY0UT,.SERR,.HERR 

•GL0BL 

PRTDEC 

;Subroutine to print a word in decimal 



;Are we under TSX-Plus? 

START: .SERR 


;Stop error aborts 

MOV 

//TSXLN, R0 

;Set up EMT request to 

EMT 

375 

;Get TSX-Plus line number 
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BCS 

NOTTSX 

;If error, not under TSX-Plus 


MOV 

RO.LINE 

;Save it 


.HERR 


;Enable error aborts 


.PRINT 

//LINMSG 

;Display line number message 


MOV 

LINE.RO 

;Recall line number 


CALL 

PRTDEC 

;Display line number 


.PRINT 

//TRMMSG 

;Display term type message 


MOV 

//TTYPE, RO 

;Set up EMT request to 


EMT 

375 

;Get terminal type from TSX-Plus 




;Returns into RO 


ASL 

RO 

;Convert to word offset 


.PRINT 

TYPE(RO) 

;Print type from index into table 


.EXIT 


;All done 

NOTTSX: 

.PRINT 

//TSXERR 

;Say we are not under TSX-Plus 


.EXIT 



LIKE: 

.WORD 

0 

;Storage for TSX line number 

TERM: 

.WORD 

0 

;Storage for TSX term type code 

TSXLN: 

.BYTE 

0,110 

;TSX line number EMT parameters 

TTYPE: 

.BYTE 

0,137 

;TSX term type EMT parameters 

; Table 

of pointers to TSX term 

i type names 


.EVEN 



TYPE: 

.WORD 

UNK,VT52,VT100, 

HAZEL,ADM3A,LA3 6,LAI20,DIABLO,QUME 


•NLIST 

BEX 


LINMSG: 

.ASCII 

/TSX-Plus line 

number: /<200> 

TRMMSG: 

.ASCII 

<15><12>/Terminal type: /<200> 

TSXERR: 

.ASCIZ 

/?LNTT-F-Not running under TSX-Plus/ 

UNK: 

.ASCIZ 

/Unknown/ 


VT52: 

.ASCIZ 

/VT-52/ 


VT100: 

.ASCIZ 

/VT-100/ 


HAZEL: 

.ASCIZ 

/Hazeltine/ 


ADM3A: 

.ASCIZ 

/ADM3A/ 


LA36: 

•ASCIZ 

/LA36/ 


LA120: 

.ASCIZ 

/LA120/ 


DIABLO: 

•ASCIZ 

/Diablo/ 

;Diablo and Qume are equivalent 

QUME: 

.ASCIZ 

/Qume/ 

;Diablo and Qume are equivalent 


•END START 


7.3 Determining the terminal type 

The following EMT will return in RO a value that indicates what type of 
time-sharing terminal is being used with the line. The form of the EMT is: 
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EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,137 

The terminal type is specified either when the TSX—Plus system is generated or 
by use of the SET TT command (e.g., SET TT VT100). The terminal type codes 
which are currently defined are listed below. The types Diablo and Qume are 
functionally equivalent. 


Terminal-type Code 


(Unknown) 0 
VT52 1 
VT100 2 
Hazeltine 3 
ADM 3 A 4 
LA36 5 
LA120 6 
Diablo & Qume 7 


A type code of 0 (zero) is returned if the terminal type is unknown. 

Example: 

See the example program LNTT in the section on determining the TSX-Plus line 
number. 

7.4 Determining or changing the user name 

When using the LOGON system access program, each user is assigned both a user 
name and a project, programmer number. TSX-Plus provides an EMT which allows 
an application program to obtain the user name or (with operator privilege) to 
change it. User names may be up to twelve characters in length. If the LOGON 
program is not used, the user name will initially be blank, although it may be 
changed to a non-blank name. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block to determine the user name: 

.BYTE 0,147 
•WORD buff-addr 

where "buff-addr" is a pointer to a 12 byte area to contain the user name which 
is returned. 

To change the current user name, RO should instead point to the following 
argument block: 
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where "buff-addr" is a pointer to a 12 byte area containing the new user name. 
Operator privilege is required to change the user name. If changing the user 
name is attempted without operator privilege, the the name will not be changed 
and the carry bit will be set on return. 

Example: 


.TITLE GSUNAM 
.ENABL LC 

; Demonstrate TSX-Plus EMT to get/set user name 

ERRBYT = 52 ;EMT error code location 


•MCALL .PRINT,.EXIT 


START: 

.PRINT 

//NAMEIS 

;Preface user name 


MOV 

//GSUNAM, RO 

;Point to EMT arg block to 


EMT 

375 

;Get user name 


.PRINT 

//NAMBUF 

;And display it 


MOV 

//NEWNAM, NAMADD 

;Point to new user name 


INCB 

GSUNAM 

;Set low bit to set name 


MOV 

//GSUNAM, RO 

;Point to EMT arg block to 


EMT 

375 

;Set new user name 


BCC 

1$ 

;Error? 


.PRINT 

//NOPRIV 

;Must have operator privilege 

1$: 

.EXIT 




.NLIST 

BEX 


GSUNAM: 

.BYTE 

0,147 

;EMT arg block to get user name 

NAMADD: 

.WORD 

NAMBUF 

;Pointer to receive area 

NAMBUF: 

. BLKW 

6 

;Six word name area (12 bytes) 


.WORD 

0 

;Make it ASCIZ 

NEWNAM: 

•ASCII 

/CHAUNCY / 

;The new name (12 bytes) 

NAMEIS: 

.ASCII 

/Your current 

user name is: /<200> 

NOPRIV: 

•ASCIZ 

/Operator privilege necessary to set user name. 


.END 

START 



7.5 Controlling the size of a job 

Under RT-11, the .SETTOP EMT is used to set the top address of a job. The 
TSX-Plus .SETTOP EMT does not actually alter the memory space allocated to a 
job but simply checks to see if the requested top of memory is within the 
region actually allocated to the job and if not returns the address of the top 
of the allocated job region. The TSX-Plus .SETTOP EMT was implemented this way 
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because many programs written for RT-11 routinely request all of memory when 
they start regardless of how much space they actually need. 

The memory space actually allocated for a job can be controlled by use of the 
"MEMORY" keyboard command or by use of the EMT described below. The memory 
size specified by the most recently executed MEMORY keyboard command is 
considered to be the "normal" size of the job. The EMT described here can be 
used to alter the memory space allocated to a job but the job size reverts to 
the normal size when the job exits or chains to another program. 

The form of the EMT used to change a job's size is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,141 
.WORD top-address 

where "top-address" is the requested top address for the job. If this address 
is larger than the allowed size of a job, the job will be expanded to the 
largest possible size. On return from the EMT, RO contains the address of the 
highest available word in the program space. 

A program is not allowed to change its size if it was started by use of the 
"RUN/DEBUG" command or the system was generated without allowing program 
swapping. In either of these cases the EMT operates exactly like a .SETTOP 
request (i.e., the requested program top address will not be allowed to exceed 
the normal program size). 

See also the description of the SETSIZ program in Appendix A for information 
about how the default memory allocation for a program can be built into the SAV 
file for the program. 

Example: 

See the example program CKSTAT in the section on determining job status 
information. 

7.6 Obtaining TSX-Flus system values 

The .GVAL EMT that is normally used to obtain RT-11 system values can also be 
used to obtain TSX-Plus system values. Although a simulated RMON is normally 
mapped into each job so that it may directly access fixed offsets into RMON, 
the .GVAL function is the preferred method for obtaining system values. Under 
TSX-Plus, the simulated RMON need not be mapped into a job's virtual address 
space (see Chapter 8). The .GVAL EMT will still function correctly even if 
RMON is not mapped into the job. In addition to the positive offset values 
which are documented for use with RT-11, the following negative offset values 
may be used to obtain TSX-Plus system values: 
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Offset Value 

-2. Job number 

-4. "Lead-in" character used for terminal control options 
-6. 1 if privileged job; 0 if non-privileged job 
-8. 1 if PAR 7 mapped to I/O page; 0 otherwise 

-10. Project number job is logged on under 
-12. Programmer number job is logged on under 
-14. TSX-Plus incremental license number 
-16. Current job priority 
-18. Maximum allowed job priority 
-20. Number of blocks per job in SY:TSXUCL.TSX 
-22. Job number of primary line (0 for primary line) 

-24. Name of system device (RAD50) 

(may not correspond to current SY assignment) 

-26. Minimum fixed-high-priority value 
—28. Maximum fixed—low-priority value 

As with the standard .GVAL function, the system values are returned in R0 
Example; 


.TITLE TSGVAL 
.ENABL LC 


;Demonstrate usage of .GVAL with both positive (RT-11) 
; and negative (TSX-Plus) offsets 


•MCALL .GVAL,.PRINT,.EXIT 


.GLOBL PRTDEC 
.GLOBL PRTR50 


;Subroutine to print a word in decimal 
;Subroutine to print a RAD50 word 


SYSGEN =372 


;RM0N offset to sysgen options word 


START: .GVAL 

TST 
BPL 
.PRINT 
.GVAL 
CALL 
.PRINT 
.GVAL 
CALL 
.PRINT 
.GVAL 
CALL 
.GVAL 
TST 
BEQ 


//AREA,//SYSGEN 
R0 

9$ 

//LICENS 
//AREA,//-14. 
PRTDEC 
//SYSTEM 
//AREA, //-24. 
PRTR50 
//JOBNUM 
//AREA,//-2 
PRTDEC 
//AREA, //-2 2. 
R0 
9$ 


;Examine system options word 
;See if we are running TSX-Plus 
;Exit if not 
; "License // is" 

;0btain last 4 digits of license // 
;And display it 
;"Started from" 

;Get system device 
;And display it 
;"Job // is” 

;Get TSX-Plus job number 
;Display the job number 
;See if this is the primary line 
;0 if primary 
;Done if so 
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9$: 

.PRINT 

.EXIT 

//VIRT ;Else say virtual 

job 

AREA: 

LICENS: 

SYSTEM: 

JOBNUM: 

VIRT: 

.BLKW 

.NLIST 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

2 ;2 word EMT arg area 

BEX 

/TSX-Plus license number /<200> 

<15X12>/TSX-Plus started from /<200> 

/:/<15><12>/TSX-Plus line number /<200> 
/ (This is a virtual line)/<200> 


.END 

START 



7.7 Determining job status information 

The information about various jobs on the system which is displayed by the 
SYSTAT command may also be obtained by application programs. An EMT is 
provided with several subfunctions to obtain the desired job status infor¬ 
mation. This EMT may obtain information about any job on the system, not only 
itself. The form of the EMT is: 

EMT 375 


with RO pointing to the following argument block: 
.BYTE 0,144 

. BYTE line-//, sub-function 
.WORD buf-address 


where ,, line-// ,, is the number of the time-sharing line about which information 
is to be returned. Line numbers are in the range 1 up to the highest valid 
line number for the system. "Sub-function” is a function code which indicates 
the type of information to be returned by the EMT (see below). "buf-address" 
is the address of the first word of a 2 word buffer area into which the 
returned value is stored. Note: some of the functions only return a single 
word value in which case the value is returned into the first word of the 
buffer area. 

If an error occurs during the execution of the EMT, the carry-flag is set on 
return and the following error codes indicate the type of error: 


Errors: 

Code Meaning 


0 Indicated line number is not currently logged on. 

1 Invalid sub-function code. 

2 Invalid line number (0 or higher than largest valid line number). 


Each of the sub-functions 


is described below: 
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Subfunction # 0 “ Check status of line. The value returned contains bit flags 
that indicate the status of the job. The following bit flags are defined: 

000001 = This is a virtual line. 

000002 = This is a detached job line. 

000100 = Job has locked itself in memory. 

000200 = Job has operator privilege. 

Subfunction #_ 1 ^Z Get job's execution state. This subfunction returns a code 
that indicates a job's current execution state. The following code values are 
defined: 

1 = Non-interactive high priority run state. 

2 = Normal priority run state. 

3 = Fixed-low-priority run state. 

4 = Waiting on input from the terminal. 

5 = Waiting for output to be written to terminal. 

6 = Doing a timed wait. 

7 = Suspended because .SPND EMT done. 

8 = Waiting for access to a shared file. 

9 = Waiting for a inter-job message. 

10 = Waiting for access to USR (file management) module. 

11 = Waiting for non-terminal I/O to finish. 

12 = Waiting for access to spool file. 

13 = Interactive high priority run state. 

14 = Fixed-high-priority run state. 

15 = Waiting for memory expansion. 

Subfunction #_ 2_ “ Determine amount of memory used by job. This function 
returns the number of 256-word blocks of memory that are currently being used 
by the job, including PLAS regions. 

Subfunction # 3 ^Z Determine connect time for job. This function returns the 
number of minutes that a job has been logged onto the system. 

Subfunction # 4 — Determine position of job in memory. This function returns 
the 256-word block number of the start of the memory area allocated to the job. 

Subfunction // 5 — Get name of program being ru n by job. This function returns 
a 2 word valued The two words contain the RAD50 value for the name of the 
program currently being run by the job. 

Subfunction # 6 — Get project and programmer number for job. This function 
returns a two word value. The first word contains the project number that the 
job is logged on under; the second word contains the programmer number. 
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Subfunction Get CPU time used by job. This function returns a two word 

value that contains the number of clock-ticks of CPU time used by the job. The 
first word contains the high-order 16-bits of the value, the second word 
contains the low-order 16-bits. 

Subfunction 8 &et current job execution priority. This function returns 
one word that contains the current job execution priority level (0-127). 

Example: 


.TITLE CKSTAT 
•ENABL LC 


; Demonstration of MEMTOP, JSTAT and SNDMSG EMTs of TSX-Plus 


ERRBYT - 52 
PRGNAM = 5 


;EMT error code location 

;JSTAT subfunction code to get prog, name 


.MCALL .TWAIT,.EXIT 


START: MOV //MEMTOP,R0 ;Point to EMT arg block to 

EMT 375 ;Set job size 

;0nly works in swapping environment, otherwise behaves like .SETTOP 


CMP 
BHIS 
.EXIT 

AGAIN: MOVB 

CHECK: MOV 
EMT 
BCS 
CMP 
BNE 
CMP 
BNE 

;Send a message 

;(Each message 
MOVB 
MOV 
MQV 
EMT 
MOV 
MOV 
EMT 
MOV 
MOV 
EMT 
MOV 
MOV 
EMT 


R0, //HILIM 
AGAIN 


;See if we got what we wanted 
;Go on if so 

;else quit (can't disp err msg from det line) 


//I, LINE 
//JSTAT, R0 
375 

ERRTYP 

BUFADD,DUNJUN 
NEXT 

BUFADD+2,DUNJUN+2 
NEXT 

to the offending 
must be < 88. byte 
LINE,Y00H00 
//MESAG1 ,MSGADD 
/ASEND,R0 
375 

//MESAG2 ,MSGADD 
//SEND,R0 
375 

//MES AG3, MS GADD 
//SEND, R0 
375 

//MESAG4,MSGADD 
//send, ro 
375 


Check all lines starting with //I 
Point to EMT arg block 
Get name of job being run 
Go find out what kind of error 
Is this line goofing off? 

No, proceed 

;May be, check for sure 
No, proceed 
line 
s) 

Who is the guilty party? 

Prepare part one of message 

Point to EMT arg block to 

Send a message to that line 

Prepare for part two of the message 

Point to EMT arg block to 

Send part 2 of message 

Prepare for part three of the message 

Point to EMT arg block to 

Send part 3 of message 

Prepare for part four of the message 

Point to EMT arg block to 

Send part 4 of message 
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NEXT: INCB 

LINE 

;Try next line 

CMPB 

LINE,MAXLIN 

;Have we checked them all? 

BGT 

SLEEP 

;Yes, wait awhile 

BR 

CHECK 

;Go check the rest of the lines 

SLEEP: .TWAIT 

//AREA, //TIME 

, Come back in 5 minutes 

BR 

AGAIN 

;And try again 

ERRTYP: CMPB 

0//ERRBYT, //I 

Which error is it 

BLT 

NEXT 

,0 —> line not logged on, try next line 

BEQ 

2$ ; 

1 —> invalid sub-function code, give up 

MOVB 

LINE,MAXLIN 

,2 —> line > last valid line 

DECB 

MAXLIN 

Largest valid line number 

BR 

SLEEP ; 

should only happen first time 

2$: .EXIT 


Invalid code should never happen 



Might as well kill job 

MEMTOP: .BYTE 

0,141 

Argument block for MEMTOP EMT 

.WORD 

HILIM 

Upper address limit 

JSTAT: .BYTE 

0,144 

Argument for JSTAT EMT 

LINE: .BYTE 

0 

TSX-Plus line number to be checked 

SUBFUN: .BYTE 

PRGNAM 

EMT subfunction 

.WORD 

BUFADD 

Address of 2-word buffer for returned value 

BUFADD: .BLKW 

2 

2 word buffer to hold stat result 

MAXLIN: .BYTE 

30. 

Maximum number of lines under TSX-Plus 

.EVEN 


Will be altered to max valid line # 

SEND: .BYTE 

0,127 

EMT arg block to send a message 

YOOHOO: .WORD 

0 

Destination line number 

MSGADD: .WORD 

MESAG1 

Message to be sent 

AREA: .BLKW 

2 

.TWAIT arg area 

TIME: .WORD 

0 

time high word 

.WORD 

5*60.*60. 

5min * 60.sec/min * 60.ticks/sec 

•NLIST 

BEX 


DUNJUN: .RAD50 

/DUNJUN/ : 

;Name of illicit program 

MESAG1: .ASCII 

<7><15X12> 


.ASCII 

/**********************************/<!3X12> 

.ASCIZ 

/* 

*/<15><12> 

MESAG2: .ASCII 

/* Continued use of this system */<15X12> 

.ASCIZ 

/* for game playing will result */<15X12> 

MESAG3: .ASCII 

/* in loss of user privileges! ! */<15X12> 

.ASCIZ 

/* 

*/<15X12> 

MESAG4: .ASCIZ 

/********************************** /<15X12X7> 

HILIM: .END 

START 



7.8 Setting job priority 

Jobs may be assigned priority values in the range 0 to 127 to control their 
execution scheduling relative to other jobs. The priority values are arranged 
in three groups: the fixed-low-priority group consists of priority values from 
0 up to the value specified by the PRILOW sysgen parameter; the fixed-high- 
priority group ranges from the value specified for the PRIHI sysgen parameter 
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up to 127; the middle priority group ranges from (PRILOW+1) to (PRIHI-1). The 
following diagram illustrates the priority groups: 

+-+ 

127 — >| I 

I Fixed 
I high 

I priorities | 

PRIHI -->| I 

H-+ 

I I 

Normal 

PRIDEF —>| job 

I priorities I 

I I 

+-+ 

PRILOW —>| I 

| Fixed 

| low | 

I priorities I 

0 — > I I 

H-+ 

Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other jobs. A job with a fixed priority is allowed to 
execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 
fixed-low-priority group is intended for use by very low priority background 
tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive, time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed-priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority of jobs 
in the normal job priority range will never be reduced below the value of 
(PRILOW+1). 
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The following EMT can be used to set the job priority from within a program. 
The job priority can also be set from the keyboard with the SET PRIORITY 
command. The current job priority, maximum allowed priority, and fixed-high- 
and fixed-low-priority boundaries may be determined with the .GVAL request. 
See the TSX-Plus System Manager's Guide for more information on the signifi¬ 
cance of priority in job scheduling. The form of this EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE 0,150 
•WORD value 

where "value" is the priority value for the job. The valid range of priorities 
is 0 to 127 (decimal). The maximum job priority may be restricted by the 
system manager. If a job attempts to set its priority above its maximum 
allowed priority, its priority will be set to the maximum allowed. This EMT 
does not return any errors. 

Example: 


.TITLE GSPRI 
.ENABL LC 


; Demonstrate EMT to set job priority 



.MCALL 

.GVAL,.GTLIN,.PRINT,.EXIT 


.GLOBL 

PRTDEC 


CURPRI 

= -16. 

J 

GVAL offset to get current priority 

MAXPRI 

= -18. 

9 

GVAL offset to get maximum priority 

START: 

.PRINT 

//CURIS 

"current priority is" 


.GVAL 

//AREA,//CURPRI 

Obtain current job priority in RO 


MOV 

R0,R1 

Save it 


CALL 

PRTDEC 

and display it 


.PRINT 

//MAXIS 

"maximum priority is" 


.GVAL 

//AREA, //MAXPRI 

Obtain maximum allowable job priority 


MOV 

R0,R2 

Save it 


CALL 

PRTDEC 

and display it 


ADD 

//10. ,R1 

Try to boost priority by 10 


CMP 

Rl,R2 

Unless exceeds maximum 


BLE 

1$ 

Use 10 larger if <= maxpri 


MOV 

R2,R1 

Else use maxpri 

1$: 

MOV 

Rl.NEWPRI 

Set new priority in EMT arg block 

MOV 

//SETPRI.RO 

Point to EMT arg block to 


EMT 

375 

Sset new job priority 


. PRINT 

//NEWIS 

"new priority is" 


.GVAL 

//AREA, //CURPRI 

Obtain new priority 
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CALL 

• EXIT 

PRTDEC 

; and display it 

AREA: 

• BLKW 

10 

;General EMT arg block 

SETPRI: 

• BYTE 

0,150 

;EMT arg block to set job priority 

NEWPRI: 

• WORD 

50. 

;New job priority goes here 


•NLIST 

BEX 


CURIS: 

•ASCII 

/Current job priority = /<200> 

MAXIS: 

•ASCII 

<15X12>/Maximum 

job priority = /<200> 

NEWIS: 

•ASCII 

<15><12>/- New - 

job priority = /<200> 


• END 

START 



7.9 Forcing [non]interactive job characteristics 

The following EMT can be used to cause a job to be scheduled either as an 
interactive job or as a non-interactive job. Programs which do a large amount 
of terminal input, but which are not truly interactive jobs in the usual sense, 
such as file transfer programs, should use this EMT to avoid excessive 

interference with normal interactive time-sharing jobs. This feature may also 

be selected with the R[UN]/N0N1NTERACTIVE command. See the TSX—Plus System 

Manager's Guide for more information on job scheduling and the significance of 
interactive vs. non-interactive jobs. 

The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,153 
.WORD mode 
.WORD 0 

If the value of "mode" is 0, then the job will never be scheduled as an 

interactive job. If "mode” is 1, then the job will be scheduled as other 
interactive jobs are, dependent on terminal input. 

Example: 

.TITLE NONINT 
•ENABL LC 

; Demonstrate EMT to schedule job as interactive or non-interactive 

•MCALL .TTYIN,.TTYOUT,.PRINT,.EXIT 

JSW = 44 ;Job Status Word address 

TTSPC = 10000 ;TT special mode bit (single-char) 
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CTRLZ 

= 32 


;ASCII CTRL-Z (move on command) 

START: 

MOV 

//SINGLE.RO 

;Point to EMT arg block to 


EMT 

375 

;Turn on single character activation 


BIS 

//TTSPC,@#JSW 

;Finish turning on single char mode 


MOV 

//NONINT, RO 

;Point to EMT arg block to 


EMT 

375 

;Schedule this as non-interactive job 


.PRINT 

//SLOW 

;"May be slow now if system busy" 

1$: 

.TTYIN 


;Get a char 


CMPB 

RO,//CTRLZ 

; If CTRL-Z 


BEQ 

2$ 

;Then move on 


.TTYOUT 


;Else echo it back (we have to echo 




; when in single char mode) 


BR 

1$ 

;And repeat 

2$: 

MOV 

#1,SELECT 

;Want to be interactive now 


MOV 

//NON I NT, RO 

;Point to EMT arg block to 


EMT 

375 

;Schedule this as an interactive job 


. PRINT 

//FAST 

;"See how much faster now" 

3$: 

.TTYIN 


;Get a char 


CMPB 

RO,//CTRLZ 

;If CTRL-Z 


BEQ 

4$ 

;Then move on 


.TTYOUT 


;Else echo it back 


BR 

3$ 

;And repeat 

4$: 

.EXIT 



SINGLE: 

.BYTE 

0,152 

;EMT arg block to set terra option 


.WORD 

'S 

;Single char activation 


.WORD 

0 


NONINT: 

.BYTE 

0,153 

;EMT arg block to sched as [non]interactive 

SELECT: 

.WORD 

0 

;Initially make non-interactive 


.WORD 

0 



•NLIST 

BEX 


SLOW: 

.ASCII 

/Type some characters in now. If the system has several / 


.ASCII 

/interactive jobs/<15><12> 


.ASCII 

/response will 

be slow. (Control-Z to get out / 


.ASCIZ 

/of this mode. 

)/ 

FAST: 

.ASCIZ 

<15><12>/Try again. Response should be much better./ 


.END 

START 


7.10 Sending a 

message to another line 


The following EMT can be used to cause a message to display on another line's 
terminal. (This is a different feature than message communication channels.) 
The form of the EMT is: 
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EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,127 
.WORD line-number 
.WORD message-address 

where ,, line-number ,, is the number of the line to which the message is to be 
sent and ,, message-address ,, is the address of the start of the message text that 
must be in ASCIZ form. The message length must be less than 88 bytes. 

Example: 


See the example program CKSTAT in the section on determining 
job status information. 

7.11 Mount a file structure 

This EMT is used to tell TSX-Plus that a file structure is being mounted and 
that TSX-Plus should begin caching the file directory for the device. The 
effect of this EMT is the same as doing a system MOUNT keyboard command. The 
form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,134 

.WORD device-spec-address 
.WORD 0 

where "device-spec-address" is the address of a word containing the RAD50 form 
of the name of the device on which the file structure is being mounted. If 
there is no room left in the table of mounted devices, the carry bit is set on 
return and the error code returned is 1. 

Example: 


.TITLE MOUNT 
.ETNABL LC 

; Demonstrate TSX-Plus EMT to "MOUNT" (do directory caching on) a device 



.GLOBL 

IRAD50 ;SYSLIB RAD50 

conversion subroutine 

BS 

= 10 

;ASCII Backspace 


.MCALL 

•PRINT,.GTLIN,.EXIT 


START: 

.GTLIN 

//BUFFER,//PROMPT ;Ask for name 

of device 


MOV 

#R50BLK,R5 ;Point to arg 

block for next call 


**•. -> 
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CALL 

IRAD50 

;Convert ASCII device name to RAD50 

MOV 

(/MOUNT, RO 

;Point to EMT arg block to 

EMT 

375 

;Mount a file structure (directory caching) 

BCC 

START 

;Ask for more if OK 

.PRINT 

.EXIT 

//NOGOOD 

;Say it was not good 

.NLIST 

BEX 


MOUNT: .BYTE 

0,134 

;EMT arg block to mount a file structure 

.WORD 

DEVNAM 

;Pointer to RAD50 name of device 

.WORD 

0 

;Required 0 argument 

R50BLK: .WORD 

3 • 

;Nuraber of args for IRAD50 call 

.WORD 

THREE 

;Pointer to number of chars to convert 

.WORD 

BUFFER 

;Pointer to chars to convert 

.WORD 

DEVNAM 

;Pointer to RAD50 name of device 

THREE: .WORD 

3 

;Number of chars to convert 

DEVNAM: .WORD 

0 

;RAD50 representation of device name 

BUFFER: .BLKB 

80. 

;GTLIN input buffer 

PROMPT: .ASCII 

/Name of 

device to be mounted: :/<BSXBS><BSXBS><200> 

N0G00D: .ASCIZ 

/Attempt 

to MOUNT too many devices./<7> 

.END 

START 



7.12 Dismount a file structure 


This EMT can be used to tell TSX-Plus to stop doing directory caching on a 
particular drive. The effect of this EMT is the same as a DISMOUNT keyboard 
command. The form of the EMT is: 

EMT 375 

with RO pointing to an argument block of the following form: 

.BYTE 0,135 

.WORD device-spec-address 
.WORD 0 

where "device—spec—address" is the address of a word containing the RAD50 name 
of the device to be dismounted. 

Example: 


.TITLE DISMNT 
.ENABL LC 

; Demonstrate TSX-Plus EMT to "DISMOUNT" (stop caching on) a device 


•GLOBL IRAD50 
BS = 10 

.MCALL .GTLIN 


;SYSLIB RAD50 conversion subroutine 
;ASCII Backspace 


-123- 












TSX-Plus EMTs 


START: 

.GTLIN 

//BUFFER,//PROMPT 

;Ask for name of device 


MOV 

//R50BLK.R5 

;Point to arg block for next call 


CALL 

IRAD50 

;Convert ASCII device name to RAD50 


MOV 

//DISMNT, RO 

;Point to EMT arg block to 


EMT 

375 

;dismount a file structure (stop caching) 


BR 

START 

;Repeat (no errors returned) 


.NLIST 

BEX 


DISMNT: 

.BYTE 

0,135 

;EMT arg block to dismount a file structure 


.WORD 

DEVNAM 

;Pointer to RAD50 name of device 


.WORD 

0 

;Required 0 argument 

R50BLK: 

.WORD 

3 

;Number of args for IRAD50 call 


.WORD 

THREE 

;Pointer to number of chars to convert 


.WORD 

BUFFER 

;Pointer to chars to convert 


.WORD 

DEVNAM 

;Pointer to RAD50 name of device 

THREE: 

.WORD 

3 

;Number of chars to convert 

DEVNAM: 

.WORD 

0 

;RAD50 representation of device name 

BUFFER: 

. BLKB 

80. 

;GTLIN input buffer 

PROMPT: 

.ASCII 

/Name of device 

to be dismounted: :/<BS><BSXBS><BS><200> 


.END 

START 



7.13 Set terminal read time-out value 

This EMT can be used to specify a time-out value that is to be applied to the 
next terminal input operation. This EMT allows you to specify the maximum time 
that will be allowed to pass between the time that you issue a command to get 
input from the terminal and the time that an activation character is received 
to terminate the input field. You also specify with this EMT a special 
activation character that is returned as the terminating character for the 
field if the input operation times out without receiving an activation 
character from the terminal. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,117 

.WORD time-value 

.WORD activation-character 

where "time—value" is the time-out value specified in 0.5 second units and 
"activation-character" is a single character value that is to be returned as 
the last character of the field if a time-out occurs. The time value specified 
with this EMT only applies to the next terminal input field. The time value is 
reset when the next field is received from the terminal or the time-out occurs. 
a new time-out value must be specified for each input field that is to be time 
controlled. 
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Example: 


.TITLE DUNJUN 

; Demonstrate use of terminal input time-out testing 


.MCALL .TTYOUT,.TTYIN,.EXIT,.PRINT 


START: 

•TTYOUT 

r? 


1$: 

MOV 

//SETTTO, R0 

;Point to EMT arg block to 


EMT 

375 

;Set terminal input time-out 


.TTYIN 


;Get a character from the terminal 


CMP 

R0,//<15> 

;Skip over carriage returns 


BEQ 

1$ 



CMP 

R0,#<12> 

;and line feeds 


BEQ 

START 

;prompt for next char 


CMP 

RO.JTQ 

;Should we quit? 


BNE 

1$ 

;No, get next char 


.PRINT 

//DONE 

;Quit or time-out 


• EXIT 


;Bye 

SETTTO: 

.BYTE 

0,117 

;EMT arg block 


.WORD 

6*60.*2 

;6.min * 60.sec/min * 2 .half-sec-units/sec 


.WORD 

'Q 

;Activation character on time-out 


.NLIST 

BEX 


DONE: 

.ASCIZ 

/STOP - / 



.END 

START 



See also the example program CKTTIE in the section on checking for terminal 
input errors. 

7.14 Establishing break sentinel control 

The following EMT can be used to declare a completion routine that will be 
triggered when the "Break" key is pressed. The form of the EMT is 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,133 
.WORD brkchr 
.WORD cplrtn 

where "brkchr" is a user defined character that is to be declared the "Break" 
character and "cplrtn" is the address of the completion routine that is to be 
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called when the break character is received from the terminal. The specified 
completion routine will be called if the user presses either the key labeled 
"BREAK" (which transmits a long space) or types the character that is declared 
as the user-specified break character (brkchr). If no user-specified break 
character is wanted, specify the value 0 (zero) for brkchr in the argument 
block and only the real "BREAK" key will be activated. Note that on some 
systems the console terminal "BREAK" key causes entry to the hardware ODT 
module and for this reason cannot be used with this TSX-Plus function. Only 
one break routine may be specified at a time for each user. If a break routine 
was previously specified, it is cancelled when a new routine is declared. If 
an address of 0 (zero) is specified as the address of the completion routine 
(cplrtn), any previously specified break routine is cancelled and the break key 
connection is cancelled. A break routine can be used to signal an asynchronous 
request for service to a running program. A good example of its use would be 
to trigger entry to an interactive debugging program. 


Example: 


.TITLE 


BRKSNT 


;Demo use of break sentinel control 



.MCALL 

.ENABL 

•PRINT,.TWAIT, 
LC 

.EXIT 

START: 

MOV 

EMT 

//BRKSNT, RO 

375 

;Point to argument area to 
;Establish break sentinel control 


.PRINT 

.TWAIT 

//MESS AG 
//AREA, //TIME 

;Prompt for key 

;Give the user 2 seconds to hit the break key 


TST 

BNE 

.PRINT 

YES 

DONE 

//NOBRK 

;Ever see a break? 

;Yes, all done 
;No, never saw it 

DONE: 

.EXIT 



C^CMPRTN: 

.PRINT 

MOV 

RETURN 

//GOTBRK 
//I ,YES 

;Say we caught the break 
;Remember it 
;And continue 

Completion routines are ALWAYS exited with 
;RTS PC under TSX-Plus, NEVER via RTI 

BRKSNT: 

.BYTE 

.WORD 

.WORD 

0,133 

0 

CMPRTN 

;EMT arg value block to break sentinel control 
;Declare only 'BREAK' key as break char 
;Address of completion routine to be called 
;when system notices break 

YES: 

• WORD 

0 

;Flag for break seen 


& 
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AREA: 

. BLKW 

2 

;2 word arg area for .TWAIT 

TIME: 

.WORD 

.WORD 

0 

2.*60. 

;high word of time 
;2 sec * 60.tics/sec 

MESSAG: 

GOTBRK: 

NOBRK: 

.NLIST 

.ASCIZ 
.ASCIZ 

.ASCIZ 

BEX 

/You have 2 seconds to hit the break key./ 
<15><12>/Break key pressed./ 

/Never saw the break key./ 


.END 

START 



7.15 Checking for terminal input errors 

The following EMT can be used to determine if any terminal input errors have 
occurred. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,116 

On return from the EMT, the carry-flag is set if an input error has occurred 
since the line logged on or since the last time a check was made for input 
errors. The two types of errors that are monitored by this EMT are hardware 
reported errors (parity, silo-overflow, etc.) and characters lost due to 
TSX-Plus input buffer overflow. 

Example: 

.TITLE CKTTIE 
.ENABL LC 

;Check for terminal input errors 


.MCALL .PRINT,.TTYIN,.EXIT 


START: .PRINT 

//PROMPT 

;Ask to overflow buffer 

MOV 

#100.,R1 

;Set up counter for input loop 

MOV 

//SETTTO.RO 

;Point to EMT arg block to 

EMT 

375 

;Set terminal time out for 0.5 

;Note that this 

is reset after 

every activation character!!! 


;Start requesting characters. Input characters are stacked in the user 
;input buffer until an activation character is seen (e.g. carriage return). 
;So, all we have to do to overflow is enter more than the input buffer 
;size (defined in TSGEN either by DINSPC or with the BUFSIZ macro) 

;and type in too many before activating. 

;Use a time-out so we don't have to hit return. 

1$: .TTYIN ;Get a character from the terminal 
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CMPB RO,//37 ;Was it time-out activation char? 

BEQ TIMOUT ;Yes, exit loop 

SOB Rl,l$ ;Repeat for 100. characters 

;For a system with input buffer size=100. in TSGEN, we should be 
;able to overflow the buffer before v^e see an activation char 


TIMOUT: 

MOV 

//CKTTIE,R0 

;Point to EMT arg block to 


EMT 

375 

;Check for terminal input errors 


BCS 

HADERR 

;Say we had errors 


.PRINT 

.EXIT 

//NOERR 

;Say we had no errors 

HADERR: 

.PRINT 

//YESERR 

;Error message 


CMP 

Rl, //3 

;Did we fill the buffer? 

;Note that last 

two chars of input buffer are reserved 

;for activation 

chars. Any excess input is discarded. 


BLE 

TOOMNY 

;Yes, buffer overflow 


. PRINT 

.EXIT 

//HDWERR 

;No, hardware error message 

T00MNY: 

.PRINT 

.EXIT 

//OVFERR 

;Buffer overflow message 

SETTTO: 

.BYTE 

0,117 

;EMT arg block to set terminal time out 


.WORD 

20. 

;to 10 seconds (20 half sec units) 


.WORD 

37 

;Passed as activation char on time-out 

CKTTIE: 

.BYTE 

0,116 

;EMT arg block to check for input errors 


.NLIST 

BEX 


YESERR: 

.ASCIZ 

<15><12>/There 

were errors during terminal input./<7> 

OVFERR: 

•ASCIZ 

/(Probably input buffer overflow.)/ 

HDWERR: 

.ASCIZ 

/(Probably hardware error ... parity, stop bits, d^ta bits)/ 

NOERR: 

.ASCIZ 

<15><12>/There 

were no terminal input errors./ 

PROMPT: 

.ASCIZ 

/Please enter more than 100 input characters and wait. . ./ 


.END 

START 



7.16 Checking for activation characters 

The following EMT can be used to determine if any activation characters have 
been received by the line but not yet accepted by the program. The form of the 
EMT is: 


EMT 375 

with R0 pointing to the following argument block: 

.BYTE 0,123 

If there are pending activation characters, the carry-flag is cleared on return 
from the EMT; if there are no pending activation characters, the carry-flag is 
set on return from the EMT. 
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Example: 

.TITLE CKACT 
.ENABL LC 

;Demonstrate use of check for activation characters 


LEADIN 

— 

35 

;TSX-Plus program controlled terminal 
;option lead-in character 


.MCALL 

.PRINT,.EXIT, 

.GTLIN,.TWAIT,.TTYOUT 

START: 

.PRINT 

//PROMPT 

;Request some characters 
;And disallow deferred echoing 

;Do some processing. Simulated here by .TWAIT 


MOV 

#80.,R1 

;Line length counter 

1$: 

.TTYOUT 

r. 

;Tick, tock 


DEC 

R1 

;End of line? 


BNE 

2$ 

;No, go on 


.TTYOUT 

#<15> 

;New line 


.TTYOUT 

#<12> 



MOV 

#80.,R1 

;Reset line length counter 

2$: 

.TWAIT 

//AREA, //TIME 

;Wait 1 second here 

; • • • 

MOV 

//CKACT, RO 

Processing . . . 

;Point to EMT arg block to 


EMT 

375 

;Check for pending activation characters 


BCS 

1$ 

;Continue if input not complete 


.GTLIN 

//BUFFER 

;Collect the pending input 

; . . . 

CMP 

BUFFER,EX 

Do something with it 
;Exit command? 


BNE 

1$ 

;No, continue processing 


.PRINT 

.EXIT 

//BYE 


AREA: 

.BLKW 

10. 

;EMT arg block 

TIME: 

.WORD 

0,1.*60. 

;l.sec * 60.tics/sec 

CKACT: 

.BYTE 

0,123 

;EMT arg block for activation char check 

BUFFER: 

.BLKB 

81. 

;Local input buffer 


.NLIST 

.EVEN 

BEX 


EX: 

.ASCII 

/EX/ 


PROMPT: 

.ASCII 

<LEADIN>/L/ 

;Disallow deferred echoing 


.ASCIZ 

/Please enter 

up to 80 characters, then RETURN:/ 

BYE: 

.ASCIZ 

/Thank you./ 



.END 

START 
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7 .* ^ ^ Sending a_ block of characters to the terminal 


The following EMT can be used to efficiently send a block of characters to the 
terminal. The form of the EMT is: 


EMT 375 


with RO pointing to the following argument block: 

.BYTE 0,114 
.WORD buffer 
.WORD count 



where buffer is the address of the buffer containing the characters to be 
sent and "count" is a count of the number of characters to be sent. This EMT 
is much more efficient to use than a series of .TTYOUT EMT's — it has the same 
efficiency as a .PRINT EMT but it uses a count of the number of characters to 
send rather than having the character string in ASCIZ form. 

Example: 


.TITLE TTOBLK 
.ENABL LC 

;Demonstration of the use of the TSX-Plus EMT to send a block of 
;characters to the terminal. 


.MCALL .EXIT 


START: MOV 

//TTOBLK, R0 

EMT 

375 

.EXIT 



;Point to EMT arg block to 

;Send a block of chars to the terminal 


TTOBLK: .BYTE 
.WORD 
.WORD 

# .NLIST 
BUFFER: .ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 

BUFEND: 


0,114 ;EMT arg block to send a block of chars 

BUFFER ;Pointer to character buffer 

<BUFEND-BUFFER> ;Count of characters to be output 
BEX 

/This EMT is used to send a block of characters / 

/to the terminal./<15><12> 

/It is similar to .PRINT, except that it uses / 

/a count of characters/<15X12> 

/rather than a special terminating character / 

/(<0> or <200>)./<15><12> 


.END START 
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7.18 Accepting ji block of characters from the terminal 

The following EMT can be used to accept all characters from the terminal input 
buffer up to and including the last activation character entered. The form of 
the EMT is: 


375 


EMT 


with RO pointing to the following argument block: 

.BYTE 0,115 
.WORD buffer 
.WORD size 

where "buffer" is the address of the buffer where the characters are to be 
stored and "size" is the size of the buffer (number of bytes). This EMT causes 
a program to wait until an activation character is entered and then returns all 
characters received up to and including the last activation character. On 
return RO contains a count of the number of characters received. If the 
specified buffer overflows, the carry-flag is set on return. This EMT is 
substantially more efficient than doing a series of .TTYIN EMTs; it is 
particularly well suited for accepting input from page buffered terminals. 


Example: 


.TITLE TTIBLK 
.ENABL LC 


;Demonstrates the use of TSX-Plus EMT to accept a block of characters 
;from a terminal. 


MCALL .EXIT,.PRINT,.TTYIN 


START: . PRINT //PROMPT 


;Request input 

;Point to EMT arg block to 

;Accept a block of chars from the terminal 

;Save input character count 

char (and LF after CR) 

;Buffer overflow on input? 

;Yes, warn user 

;Point past last char in buffer 
;Make the input ASCIZ 
;Reproduce the input 


MOV //TTIBLK, RO 

EMT 375 

MOV R0,R1 


;Char count includes activation 


BCC 1$ 
.PRINT //0VFL0W 


1$: ADD //BUFFER,R1 


CLRB (Rl) 
.PRINT //BUFFER 
.EXIT 


TTIBLK: .BYTE 0,115 


;EMT arg block to accept block from terminal 
;Start of input buffer 

;Length of buffer in chars (May not exceed 
;input buffer size declared in TSGEN.) 


.WORD BUFFER 
.WORD <BUFEND-BUF FER> 
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•NLIST 

BEX 


PROMPT: 

.ASCIZ 

/70 character input buffer ready./ 


0VFL0W: 

.ASCIZ 

/7TTIBLK-F-Buffer overflow/ 


BUFFER: 

.ASCII 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ ;3 5 

chars 


.ASCII 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ ;35 

chars 

BUFEND: 

.ASCII 

.END 

/??/ ;TTIBLK will never write over these 

START 


7.19 Program controlled terminal options 

Programs may dynamically change various parameters related to terminal control. 
The following EMT may be used to set various program controlled terminal 
options: 


EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,152 
.WORD func tion-code 

.WORD argumen t-value 

where "function—code" is a character which specifies which option is to be set 
or changed, and "argument-value” specifies a value used only by some options. 
See the section on program controlled terminal options earlier in this manual 
for more information on the specific options which may be selected and details 
on their effects. 

7.20 Turning high-efficiency terminal mode on and off 

TSX-Plus offers a "high-efficiency” mode of terminal operation that eliminates 
a substantial amount of system overhead for terminal character processing by 
reducing the amount of processing that is done on each character. When in 
high-efficiency mode, characters are sent directly to the terminal with minimum 
handling by TSX-Plus; operations such as expanding tabs to spaces and form¬ 
feeds to line-feeds are omitted as well as input processing such as echoing 
characters and recognizing control characters such as DELETE, control-U and 
control-C. The only characters treated specially on input are user-defined 
activation characters and the user-specified break character. At least one 
user specified activation character must be declared if high-efficiency mode is 
to be used. This form of terminal I/O is designed to facilitate high-speed 
machine-to-machine communication. It can be used effectively to communicate 
with buffered mode terminals. The form of the EMT used to control high- 
efficiency mode is: 
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EMT 375 

with RO pointing to the following argument block: 


•BYTE code,120 

where "code” is 1 to turn high-efficiency mode on and 0 to turn it off. 
Example: 

•TITLE HIEFF 
•ENABL LC 

;Demonstrate the use of TSX-Plus Hi-efficiency terminal mode 


•MCALL 
START: .PRINT 

.EXIT,.PRINT 
#DCLCC 

;Make ~C an activation char 

•PRINT 

//PROMPT 

;Ask for input 

MOV 

//HIEFF, RO 

;Point to EMT arg block to 

EMT 

375 

;Turn on hi-efficiency mode 

MOV 

//TTIBLK, RO 

;Point to EMT arg block to 

EMT 

375 

;Accept a block of characters 

y • • • 

MOVB 

;Actual character count returned in RO 

Do something useful with the input? 
//15,<BUFFER-1>(R0) ;Replace the activation char with 

MOVB 

//12, BUFFER(RO) 

;Carriage return, line feed 

INC 

RO 

;Count LF for output 

MOV 

RO,<TTOBLK+4> 

;Set up count for output 

MOV 

//TTOBLK, RO 

;Point to EMT arg block to 

EMT 

375 

;Display a block of characters 

CLRB 

HIEFF 

;Get ready to turn hi-eff off 

MOV 

//HIEFF, RO 

;Point to EMT arg block to 

EMT 

375 

;Turn off hi-efficiency mode 

• EXIT 

HIEFF: •BYTE 

1,120 

;EMT arg block to turn hi-eff mode on (off) 

TTIBLK: .BYTE 

0,115 

;EMT arg block to accept a block of chars 

• WORD 

BUFFER 

;Pointer to input buffer 

• WORD 

BUFSIZ 

;Number of chars to input 

TTOBLK: .BYTE 

0,114 

;EMT arg block to display a block of chars 

.WORD 

BUFFER 

;Pointer to buffer for output 

.WORD 

BUFSIZ 

;Size of buffer to output 

BUFFER: .BLKB 

82. 

;I/0 buffer - Cannot exceed line's I/O 

BUFSIZ = . - BUFFER 

; buffer sizes declared in TSGEN 

.WORD 

0 

;Spacer in case of buffer overfill 

.NLIST 
DCLCC: .ASCII 

BEX 

<35X'DX3X200> ;Declare ~C as special activation char 

PROMPT: .ASCII 

/Please enter 1 

line of characters (~C ends)./<15X12> 

.ASCIZ 

/No special processing or echoing will be done./ 
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.END START 

7.21 Determining number of free blocks in spool file 

The following EMT will return in RO the number of free blocks in the spool 
file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

•BYTE 0,107 
Example: 

.TITLE SPLFRE 
.ENABL LC 

;Demonstrate EMT to determine number of free spool blocks 



•MCALL 

.PRINT,.EXIT 


START: 

.PRINT 

//NUMFRE 

;Preface number message 


MOV 

//SPLFRE, RO 

;Point to EMT arg block to 


EMT 

375 

;Determine number of free spool blocks 
;Number is returned in RO 


CALL 

PRTDEC 

;Display the number 


•PRINT 

.EXIT 

//BLOKS 

;End of message 


•NLIST 

BEX 


SPLFRE: 

.BYTE 

0,107 

;EMT arg to get // free spool blocks 

NUMFRE: 

.ASCII 

/The spool file 

has /<200> 

BLOKS: 

.ASCIZ 
.EVEN 

/ free blocks./ 


PRTDEC: 

MOV 

R1,-(SP) 



MOV 

R2,-(SP) 



MOV 

R0,R1 

;Get copy of number in Rl 


MOV 

#BUFEND,R2 

;Point to end of conversion buffer 


MOVB 

//200,(R2) 

;Set end for .PRINT 

1$: 

CLR 

RO 

;Clear high word for DIV 

DIV 

//10., RO 

;Get low digit 


ADD 

//'0,R1 

;Convert low digit to ASCII 


MOVB 

R1,-(R2) 

;Put into buffer 


MOV 

RO, Rl 

;Get rest of number 


BNE 

1$ 

;Repeat for all digits 


.PRINT 

R2 

;Display the result 


MOV 

(SP)+,R2 



MOV 

(SP)+,R1 
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RETURN 
.BLKB 6 
BUFEND: .WORD 0 

.END START 

7.22 Set/Reset ODT activation mode 


The following EMT can be used to set TSX-Plus to activate on characters that 
are appropriate to ODT. In this mode TSX-Plus considers all characters to be 
activation characters except digits, '$', and The form of the EMT 

is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE code,111 

where "code" = 1 to turn on ODT activation mode, and "code" = 0 to reset to 
normal mode. 

Example: 

.TITLE ACTODT 
.ENABL LC 


demonstrate EMT which sets ODT activation mode 



.MCALL 

.PRINT,.EXIT 


START: 

.PRINT 

//ODTTYP 

;Say we are entering ODT activation mode 


MOV 

//ACTODT, RO 

;Point to EMT arg block to 


EMT 

375 

;Set ODT activation mode 

1$: 

CALL 

GETLIN 

;Get some terminal input 


CMPB 

BUFFER,//'Q 

;Back to regular mode? 


BNE 

1$ 

;No, get more lines 


.PRINT 

//REGTYP 

;Say we are going back to regular activation 


CLRB 

ACTODT 

;Make arg block into RESET mode request 


MOV 

//ACTODT, RO 

;Point to EMT arg block to 


EMT 

375 

;Reset ODT activation mode 

2$: 

CALL 

GETLIN 

;Get more input 


CMPB 

BUFFER, //'Q 

;Want to quit? 


BNE 

2$ 

;No, repeat 


.EXIT 



GETLIN: 

.PRINT 

//PROMPT 

;Request some input 


MOV 

//TTIBLK.RO 

;Point to EMT arg block to 


EMT 

375 

;Accept a block of characters 
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CLRB BUFFER(RO) ;Make input string ASCIZ 

.PRINT #BUFFER ;And echo same string back 

RETURN 


ACTODT: .BYTE 
TTIBLK: .BYTE 
.WORD 
.WORD 
•NLIST 
ODTTYP: .ASCIZ 
REGTYP: .ASCIZ 
PROMPT: .ASCII 
.EVEN 
BUFFER: .BLKB 
.BYTE 
.END 


;EMT arg block to SET/RESET ODT act'n mode 
;EMT arg block to get block input from term 
;Pointer to input buffer 
;Number of input chars requested 

BEX 

/Starting ODT activation mode./ 

/Restoring regular activation mode./ 

/?/< 200 > 

79 . ;TTIBLK input buffer 

0 ;CLRB could go here on full buffer 

START 


1,111 

0,115 

BUFFER 

79. 


7.23 Determining file directory information 

This EMT returns directory information about a file. The form of the EMT is 


EMT 375 

with RO pointing to the following argument block: 


.BYTE chan,145 
.WORD dblk 
.WORD rblk 


where "chan” is a channel number in the range 0-16 (octal) that is currently 
not in use, "dblk” is the address of a 4-word block containing the RAD50 file 
specification (device, file name, extension), and "rblk" is the address of a 
7-word block that will receive the information about the file. The information 
returned in "rblk" is: 


Word 1: Size of the file (number of blocks). 

Word 2: 0—>File not protected; 1—>File is protected. 
Word 3: File creation date (standard RT-11 date format). 
Word 4: File creation time (number of 3-second units). 
Word 5: Starting block number of file. 

Word 6: Unused (reserved) 

Word 7: Unused (reserved) 


Errors: 

Code Meaning 


0 Channel is currently in use. 

1 Unable to locate specified file. 

2 Specified device is not file structured. 


- 136 - 















TSX-Plus EMTs 


Example: 


.TITLE FILINF 
•ENABL LC 


; Demonstrate TSX-Plus EMT to return Information about a file 

•MCALL .PRINT,.EXIT,.CSISPC,.TTYOUT 
•GLOBL DSPDAT,DSPTI3 


ERRBYT = 52 


;EMT error code location 


START: .CSISPC 

//OUTSPC, //DEFLT 

MOV 

//FILINF, R0 

EMT 

375 

BCC 

5$ 

MOVB 

@//ERRBYT,Rl 

ASL 

Rl 

.PRINT 

FIERR(Rl) 

.EXIT 



#0,//BUFFER ;Get file name 

;Point to EMT arg block to 
;Get information about a file 
;No error? 

;What error 

;Convert to word index 
;Explain it 


MOV 

//BUFFER.RO 

TSTB 

(R0)+ 

BNE 

10$ 

MOVB 

#200,-(R0) 

.PRINT 

//BUFFER 

.TTYOUT 

//'[ 

MOV 

FILSIZ,R0 

CALL 

PRTDEC 

TST 

PRTCTD 

BEQ 

15$ 


.TTYOUT #'P 
15$: .TTYOUT //'] 

.PRINT //SPACE2 
MOV FILDAT,R0 

CALL DSPDAT 
.PRINT //SPACE2 
MOV FILTIM.RO 

CALL DSPTI3 
.PRINT //SPACE2 
MOV FILLOC.R0 

CALL PRTDEC 



.EXIT 



•NLIST 

BEX 

FILINF: 

.BYTE 

0,145 


• WORD 

INS PC 


.WORD 

FILSIZ 

FILSIZ: 

.WORD 

0 

PRTCTD: 

.WORD 

0 


;Find the end of the file spec. 
;End? 

;No, keep looking 
;No CR,LF at end 
;File name 

;File size 

;Was file protected? 


;File creation date 
;Display date 

;File creation time (3 sec resolution) 
;Display special 3-sec time 

;File starting block // 


;EMT arg block to get file info. 
;Pointer to RAD50 file name 
;Pointer to 7 word result buffer 
;File size 

;Protected=l, unprotected=0 
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FILDAT: .WORD 

0 

FILTIM: .WORD 

0 

FILLOC: .WORD 

0 

.WORD 

0,0 

0UTSPC: .BLKW 

15. 

INSPC: .BLKW 

24. 

DEFLT: .WORD 

0,0,0,0 

FIERR: .WORD 

CINUSE 

.WORD 

N0FILE 

.WORD 

BADDEV 

BUFFER: .BLKB 

81. 

SPACE2: .ASCII 

/ /<200> 

CINUSE: .ASCIZ 

/?FILINF—] 

N0FILE: .ASCIZ 

/ 7FILINF-: 

BADDEV: .ASCIZ 

/7FILINF- 

.END 

START 


;File date (standard format) 

;File time (special 3-sec format) 
;File starting block number 
;Pad for 2 reserved words 
;Output file specifications 
;Input file specifications 
;No default extensions 
;EMT error message table 


;Input string buffer 


-Channel in use./ 

-Can't find file./ 
-Non-directory device./ 


7.24 Setting file creation time 

The time that a file is created is stored along with other directory infor- 

mation under TSX-Plus. In order to pack the time { nt ° * 8in8 F le ^^ a 
represents the file creation time in three second units. For example, it 
file was created at 11:13:22, then the special time representation woul 

13467 (decimal). 


11 hr * 60 min/hr * 60 sec/min = 39600 

13 min * 60 sec/min = 780 

22 sec = 22 

40402 seconds 


40402 sec / 3 sec/unit = 13467 3 sec units 

A utility program is provided with TSX-Plus to display the creation time and 
other directory information about a file. See Appendix C for more information 
on the FILTIM utility. 

The creation date and time for a file are automatically stored by TSX-Plus in 
the directory entry for the file at the time that the file is closed after 
being created. An EMT is provided for those unusual situat °* S * ± 

different creation time is to be specified for a file after the file 
created. The form of this EMT is. 


EMT 375 
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with RO pointing to the following argument block: 


•BYTE chan,146 
.WORD dblk 
.WORD time 


where "chan" is the number of an unused channel, dblk l! J the.address 
4-word block containing the RAD50 file specification, and time is the time 
value (in 3-second units since midnight) that is to be set as the creation time 
for the file. 


Errors: 

Code Meaning 

0 Channel is currently in use. 

1 Unable to locate specified file. 

2 Specified device is not file structured. 

Example: 


.TITLE SFTIM 
.ENABL LC 


; Demonstrate TSX-Plus EMT to set file creation time 


•MCALL .PRINT,.CSISPC,.EXIT,.GTLIN 

.GLOBL ACRTI3 {Subroutine to convert hh:mm:ss to special 

;3-sec internal time format in RO 


ERRBYT = 52 


;EMT error code location 


START: .PRINT 

.CSISPC 
.GTLIN 
MOV 
CALL 
BCC 

.PRINT 

.EXIT 

1$: MOV 

MOV 
EMT 
BCC 
MOVB 
ASL 
.PRINT 

2$: .EXIT 

.NLIST 

SFTIM: .BYTE 


//GETNAM 

//OUTSPC, //DEFLT 
//BUFFER, //GETTIM 
//BUFFER, RO 
ACRTI3 
1 $ 

//BADTIM 

R0,NEWTIM 
//SFTIM, RO 
375 
2 $ 

@//ERRBYT,RO 

RO 

SFTERR(RO) 


BEX 

0,146 


;Prompt for file name 
;Get file name in RAD50 
;Prompt for and get a time 
;Point to time input buffer 
;Get special time in RO 
;Time error? 

;Yes, incorrect format 

;Save special time 
;Point to EMT arg block to 
;Set creation time in file 
{Error? 

;Yes, get error code 
;Convert to word offset 
{Explain 


;EMT arg block to set file creation time 
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NEWTIM: 
OUTSPC: 
INSPC: 
DEFLT: 
SFTERR: 


BUFFER: 

GETNAM: 

GETTIM: 

BADTIM: 

INUSE: 

NOFILE: 

BADDEV: 


EMTs 



.WORD 

INSPC 

;Pointer to RAD50 file name 

.WORD 

0 

;Will contain new creation 

. BLKW 

15. 

;.CSISPC output files 

. BLKW 

24. 

;.CSISPC input files (first 

• WORD 

0,0,0,0 

;Default file extensions 

• WORD 

INUSE 

;SFTIM error message table 

.WORD 

NOFILE 


.WORD 

BADDEV 


• BLKB 

81. 

;.GTLIN input buffer - hold 

.ASCII 

/Set creation 

time in file: /<200> 

.ASCII 

/New creation 

time: /<200> 

.ASCIZ 

/?SFTIM-F-Invalid time./ 

♦ASCIZ 

/7SFTIH-F-Channel in use./ 

•ASCIZ 

/?SFTIM-F-Can' 

't find file./ 

.ASCIZ 

/7SFTIM-F-Non- 

-directory device./ 

.END 

START 
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8. TSX-Plus JOB ENVIRONMENT 


8.1 Virtual and physical memory 

The memory space that is accessible by a job is known as the virtual address 
space for the job. Because of the architectural design of the PDP-11 computer 
which uses 16 bits to represent a virtual memory address, the maximum amount of 
virtual address space that can be accessed at one time by a job is limited to 
65,536 (64K) bytes. Thus, the virtual addresses for a job range from 000000 to 
177777 (octal). 

The actual amount of virtual address space available to a job may be as large 
as 64Kb but it may be restricted to less than this amount. The following 
factors control the size of the virtual address space available to a job: 

1) The maximum amount of memory allowed for each job as determined by 
the HIMEM system generation parameter. 

2) The amount of memory specified with the MEMORY keyboard command 
(initialized by the DFLMEM system generation parameter). 

3) The memory limit reserved in the disk file image by the SETSIZ 
program (see Appendix A). 

4) The amount of memory acquired by use of the TSX-Plus EMT that expands 
or contracts the job space. 


The physical address space for a PDP-11 computer is not limited to 64Kb. The 
maximum physical address space depends on the model of PDP-11 and the amount of 
memory installed on the computer. LSI-11/23 and 11/34 computers can access up 
to 256Kb of physical memory. The 11/23-Plus, 11/73, 11/24 and 11/44 computers 
can access up to 4Mb of memory. 

The process by which an address in the job's virtual address space is trans¬ 
formed into an address in the physical address space is known as mapping. The 
mapping of the virtual address space for a job into the physical memory space 
assigned to the job is performed by the memory management hardware facility o 
the PDP-11 computer. This facility divides the virtual address space into 
sections, called pages , each of which can address up to 8Kb of memory. The 
mapping of a page of virtual address space to a page of physical address space 
is accomplished by setting up information in a page address register (_A_) • 
There is one page address register for each of the 8 virtual address pages. 
These registers are not directly accessible by a user job but are loaded by the 
TSX-Plus system when it starts a program, changes the size of a program, or 
switches execution between different jobs. The relationship between the 8 
pages of memory and the corresponding sections of virtual address is shown in 
the following table: 
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Page Virtual address range 


0 

1 

2 

3 

4 

5 

6 
7 


000000 - 017777 
020000 - 037777 
040000 - 057777 
060000 - 077777 
100000 - 117777 
120000 - 137777 
140000 - 157777 
160000 - 177777 


Because of the design of the memory management system in the PDP-11, it is not 
possible to divide the virtual address space more finely than 8 pages of 8Kb 
each. However, it is possible to map each page of virtual address space into 
any section of physical memory. (This facility allows TSX-Plus to keep 
multiple user jobs in physical memory and to switch rapidly among them by 
reloading the page address registers.) 

8.2 User virtual address mapping 

The virtual address space accessed by a job can be divided into five cate 
gories: 

1) Normal program space which is used by instructions and data for 


programs 


2) Simulated RMON. This is the virtual address region from 160000 to 
177777 that is mapped to a simulated RMON (RT-11 resident monitor). 

3) Extended memory windows. Programs can create regions in physical 
memory and then cause one or more pages of virtual address space to 
be mapped to the regions. 

4) Shared run-time systems. Several TSX—Plus jobs can cause a portion 
of their virtual address space to be mapped to the same area of 
physical memory. This allows several users to execute the same 
program or share common data without having to allocate a separate 
area of physical memory for each user. 

5) System 1/0 page. TSX-Plus real-time programs may map the system 1/0 
page into their virtual address space. 

These categories of virtual address space are discussed in the following 


sections 
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8.3 Normal programs and virtual programs 

Programs run under TSX—Plus may be divided into two categories; normal 
programs and virtual programs . The only difference between the two types of 
programs is the manner in which TSX-Plus handles page 7 (addresses 160000 to 
177777) of the virtual address space. In the case of normal programs, page 7 
is mapped to a simulated RMON. RMON is the name of the resident RT—11 monitor. 
When running under RT-11 this is the actual system control program. When 
running under TSX-Plus, the simulated RMON does not contain any of the 
instructions that are part of RT-11 but contains only a table that provides 
information about the system and the job. This information includes such items 
as the system version number, and information about the hardware configuration. 
The cells in this table are known as RMON fixed offsets . Their position within 
the table and their contents are documented in the RT-11 Software Support 
Manual, although not all cells are relevant to or maintained by TSX-Plus. 

The address of the base of the simulated RMON table is stored in location 54 of 
the job's virtual address space. Modern RT-11 and TSX-Plus programs should not 
directly access the RMON table but rather should use the .GVAL EMT to obtain 
values from the table. However, since some older programs and some RT-11 
utility programs directly access the RMON tables, it is mapped through page 7 
for normal programs. As a result, normal programs are restricted to using 
pages 0 to 6 (56Kb) for their own instructions and data. 

Virtual programs are programs that do not require direct access to the 
simulated RMON table. These programs may still access the RMON values with the 
.GVAL and .PVAL EMTs. Since direct access to the simulated RMON is not needed, 
page 7 is available for the program to use for its own instructions and data, 
thus providing a total of 64Kb of virtual address space. A. program may 
indicate that it is a virtual program by any of the following techniques: 

1) Set bit 10 (VIRT$ — mask 2000) in the Job Status Word (location 44) 
of the SAV file. See Appendix A for information about how this bit 
can be set by use of the SETSIZ program. 

2) Use the /V LINK switch (/XM switch for the LINK keyboard command) 
which stores the RAD50 value for "VIR in location 0 of the SAV file. 

3) Use the TSX-Plus SETSIZ program (see Appendix A) and indicate that 
more than 56Kb of memory is to be used for the program. 

8.4 Extended memory regions 


Programs running under TSX-Plus have available the Programmed Logical Address 
Space (PLAS) facility that is provided by the RT-11XM monitor. This facility 
allows a program to allocate regions of physical memory and then create virtual 
windows that can be used to access the regions. There are 7 system service 
calls (EMTs) provided for PLAS support: 
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.CRRG — Create a region 

.ELRG — Eliminate a region 

.CRAW — Create a virtual address window 

.ELAW — Eliminate a virtual address window 

.MAP — Map a virtual window to a region 

.UNMAP — Unmap a virtual window 

.GMCX — Get information about the status of a window 

A region is an area of physical memory set aside for use by a job in addition 
to its normal job space. The .CRRG EMT is used by a program to request that a 
region be created. The size of a region is not restricted to 64Kb and may be 
as large as the physical memory installed on the system (less the space used by 

the TSX-Plus system, device handlers, tables, and the remainder of t e 

program). Up to 8 regions may be created by each job. 

In order to access a region, a program must use the .CRAW and .MAP EMTs to 

create a virtual window and map the virtual window to a selected portion of the 

region. A virtual window is a section of virtual address space mapped to a 
region rather than to the normal job physical address space. Up to 8 virtua 
address windows can be created by each job. The same virtual window (i.e., t e 
same range of virtual addresses) may be mapped to different regions or 
different sections of the same region at different times by use of the .MAP 
EMT. This allows a program to selectively access different sections of code or 
data in extended memory regions during the course of its execution. 

When an extended memory region is created by use of the .CRRG EMT, space is 
allocated in physical memory and in a TSX-Plus region swap file. Whenever a 
job is swapped out of memory, its extended memory regions are swapped to the 
region swap file. Space in the region swap file is allocated and deallocated 
dynamically as regions are created and eliminated. In order to create a 
region, space must be available in physical memory and in the region swap file. 

The PLAS facility is most commonly used implicitly through the virtual overlay 
and virtual array features. Using the PLAS facilities, it is possible for a 
single job to use all of the physical memory space available on a system 
(exclusive of the space used by the TSX-Plus system, handlers, tables, etc.). 
Proper use of the PLAS facilities such as with reasonable size virtual overlays 
or arrays can lead to substantial performance improvements for programs. 
Excessive use of memory space with the PLAS facility can lead to excessive jo 
swapping and degraded system performance. 


8.5 Shared run-time systems 

A shared run-time system is a program or data area in physical memory 
be”accessed by multiple TSX-Plus jobs. Shared run-time systems are 
similar to extended memory regions in that they are both allocated in 
memory areas and must be accessed by mapping a portion of the jobs 
address space to the physical memory area. The difference is that 
memory regions are private to the job that creates them and may not be 
by any other job. Shared run-time systems can be simultaneously 


that can 
somewhat 
extended 
virtual 
extended 
accessed 
accessed 
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(hence "shared”) by any number of TSX-Plus jobs. Another difference between 
regions and shared run-time systems is that regions can be created dynamically 
and can be swapped out of memory; shared run-time systems are specified when 
the system is generated and reside in memory as long as the system is running. 
See Chapter 12 for more information on shared run-time systems. 

8.6 Access to system I/O page 

The system I/O page is an 8Kb section of addresses which is not connected with 
ordinary memory but rather is used to control peripheral devices and hardware 
operation. Access to the I/O page is risky in that a program can interfere 
with peripheral devices and cause system crashes. For this reason, programs do 
not ordinarily have access to the I/O page. However, a program that is running 
with TSX-Plus real-time privilege may issue a system service call to cause page 
7 (160000-177777) of the job's virtual address space to be mapped to the system 
I/O page. See Chapter 11 for more information on real-time programs. 

8.7 VM pseudo-device handler 

While the VM handler is not actually mapped into a job's memory space, its use 
can dramatically increase job performance. The VM handler enables the use of a 
portion of physical memory as a pseudo-disk device. This permits very rapid 
access to programs and data which are placed on the VM unit. For programs such 
as compilers which heavily utilize overlay segments, a considerable speed-up 
can be achieved by loading them onto the VM device. A similar improvement for 
overlaid programs can also be obtained with the general data cache facility. 
However, when the data cache is full the least recently used blocks are lost. 
The presence of particular programs and their overlay segments in memory can be 
guaranteed by copying them to the VM pseudo-device. Another example of the 
usefulness of the VM device is with compilers which heavily use temporary work 
files. Depending on the number of write operations, which are not helped by 
general data caching, significant improvements in speed can be obtained by 
directing the work files to the VM pseudo-device. 

In order to use the VM device, it must be included in the device definitions 
during TSX-Plus system generation. An upper limit must also be placed on the 
amount of memory available to TSX-Plus. The physical memory above that 
available to TSX-Plus can then be used as a memory based pseudo-disk. If for 
some reason, it is desirable to use less than all of the memory above the top 
of TSX-Plus, the SET VM BASE command can be used to restrict the memory 
available to VM. Each time TSX-Plus is restarted, VM must be initialized just 
as you would for a new physical disk or a fresh logical subset disk. For 
example: 

INITIALIZE VM: 

Only one unit (VMO:) is available; however, logical subset disks may be created 
within the VM pseudo-device to partition it if necessary. On initialization, 
the VM handler automatically determines the amount of memory available to it. 
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See the TSX-Plus System Manager's Guide for more information on the use of data 
caching (general and shared files) and the VM pseudo-disk. 
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9. SHARED FILE RECORD LOCKING 


TSX-Plus allows several programs to have the same file open simultaneously. In 
order to control access to such files, TSX-Plus provides system calls to "lock" 
shared files and records within shared files. Through the record locking 
facility a program may gain exclusive access to one or more blocks in a file by 
locking those blocks. Other users attempting to lock the same blocks will be 
denied access until the first user releases the locked blocks. The TSX-Plus 
shared file facility also provides data caching on blocks being read from 
shared files. 

Note that shared file access protection is only meaningful for cooperating jobs 
requesting shared access. This scheme does not prevent other jobs from opening 
or writing to files if those jobs do not adhere to the file sharing protocol. 

The usual protocol for updating a shared file being accessed by several users 
is as follows. 

1) Open file. 

2) Tell TSX-Plus that file is "shared". 

3) Lock all blocks in file which contain desired record. 

4) Read locked blocks into memory. 

5) Make update to record. 

6) Write updated blocks to file. 

7) Unlock blocks. 

8) Repeat steps 3-7 as needed. 

9) Close file. 

DIBOL record locking procedures 

Subroutines to control record locking from within DIBOL programs are provided 
with TSX-Plus. These are discussed in Appendix B. 

Record locking from other languages 

Record locking may be interfaced to other languages with appropriate subroutine 
calls. Record locking under COBOL-Plus is built into the run-time library 
provided with COBOL-Plus. The remainder of this chapter describes the 
techniques used to control shared file access and record locking. 

9.1 Opening a shared file 

Before a file can be used with shared access it must be opened by using a 
standard .LOOKUP EMT. After the file has been successfully opened, the 
following EMT may be used to declare the file to be opened for shared access. 
The form of this EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE chan,125 
•WORD access-code 

where "chan" is the number of the I/O channel open to the desired file and 
"access-code" is a value indicating the type of access protection desired for 
the file. The following access codes are recognized: 
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Code 

Protection 

Access 

0 

Exclusive 

Input 

1 

Exclusive 

Update 

2 

Protected 

Input 

3 

Protected 

Update 

4 

Shared 

Input 

5 

Shared 

Update 


The access**code specifies two things: The type of access that you intend to 
make to the file (input only or update) and the type of access that you are 
willing to grant to other users of the file. There are three protection 
classes: Exclusive, Protected and Shared. Exclusive access means that you 
demand exclusive access to the file and will allow no other users to access the 
file in any fashion (input or update). Protected access means that you will 
allow other users to open the file for input but wish to prohibit any other 
users from opening the file for update. Shared access means that you are 
willing to allow other users to open the file for both input and update access. 

When this EMT is executed, TSX-Plus checks your specified protection mode and 
access type with that previously declared for the file by other users. If an 
access conflict arises because of your specified access characteristics an 
error code of 4 is returned for the EMT. If no access conflict is detected, 
your specified access code is saved with the file and will be used to check for 
conflicts with future shared access requests issued by other users. 

Normally all files that are declared to TSX-Plus using this EMT are enabled for 
use of the data caching facility (see description below). However, in some 
cases it may be desirable to suppress data caching for certain files. For 
example, sequential access files usually benefit little from data caching and 
enabling data caching for these files causes the data cache buffers to be used 
non-productively when they could be providing a better service for other types 
of files. To disable data caching for a file set bit 8 (octal 400) in the 
access-code word. When shared access is declared with bit 8 set, new data is 
not brought into the data cache when the file is read. However, if the data 
being read is already stored in the cache because of a read by another user, it 
is used. When data being written to a file is currently stored in the cache, 
the data in the cache is updated even if the file is declared to be non-cached. 

It is possible to have several channels simultaneously open to different shared 
files. The exact number of channels that can be open to shared files and the 
total number of shared files that may be opened are specified when the TSX-Plus 
system is generated. 

Once all access to a shared file is completed, the I/O channel should be closed 
using the standard .CLOSE or .PURGE EMT's. See the next section for infor¬ 
mation about saving the status of a channel that has been opened to a shared 
file. 
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The error codes that can be returned by this EMT are listed below: 


Errors: 

Code Meaning 


1 Channel has not been opened to a file. 

2 Too many channels opened to shared files. 

3 Too many shared files open. 

4 File protection-access conflict 

Example: 


.TITLE SHARED 
.ENABL LC 


; This program cooperates with the example program (SHARE2) in the 
; following section to demonstrate shared file access protection. 


.MCALL .PRINT,.GTLIN,.TWAIT,.EXIT,.READW 
.MCALL .LOOKUP,.CLOSE,.SAVESTATUS,.REOPEN,.PURGE 


ERRBYT =52 
EXUP = 1. 

PRIN = 2. 
BUFSIZ = 256. 


;EMT error byte 

;Shared file access code: Exclusive, Update 
;Shared file access code: Protected, Input 
;Number of words in a disk block 


START: 


1 $: 


2 $: 


3$: 


4$: 


.LOOKUP 

BCC 

.PRINT 

.EXIT 

MOV 

MOV 

EMT 

BCC 

JMP 

.READW 

BCC 

.PRINT 

.EXIT 

.PRINT 


//AREA, #0, #SHR1 

1 $ 

//LKPERR 


;0pen SHR1.DAT 
;Branch if OK 
;Lookup error message 


//EXUP, <SHRFIL+2> ;Set Exclusive, Update access 
//SHRFIL,R0 ;Point to EMT arg block to 

375 ;Declare SHR1.DAT as a shared file 

;with Exclusive and Update access 
2$ ;Branch if sharing OK 

EMTERR ;Explain the error and quit 

//AREA,//0,//BUFFER,//BUFSIZ,//0 ;Read block 0 of SHR1.DAT 
3$ ;Branch if read OK 

//RDWERR ;Say there was a read error 


//BUFFER 


;Print out the file (must have 0 or 200 byte) 


.SAVESTATUS //AREA,//0,//BLOK 1 ;Save channel 0 status for reuse 


BCC 

.PRINT 

.EXIT 

MOV 

EMT 

.PURGE 

.LOOKUP 

BCC 


4$ 

//SVSERR 

//SAVSHR,R0 

375 

#0 

//AREA, //0, //SHR2 
3$ 


;Branch if savestatus OK 
;Savestatus error message 

;Point to EMT arg block to 
;Save shared file status 
;Purge the channel for reuse 
;0pen SHR2.DAT 
;Branch if OK 
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.PRINT 

.EXIT 

//LKPER2 

;Say bad lookup on SHR2 

5$: 

MOV 

//PRIN,<SHRFIL+2> 

;Set Shared, Input access 


MOV 

#SHRFIL.RO 

;Point to EMT arg block to 


EMT 

375 

;Declare SHR2.DAT as a shared file 


BCC 

6$ 

;Branch on no error 


JMP 

EMTER2 

;Say error on SHR2 sharing 

6$: 

.READW 

//AREA, #0,//BUFFER 

, #BUFSIZ,//0 ;Read block 0 of SHR2.DAT 


BCC 

7$ 

;Branch if read OK 


. PRINT 
.EXIT 

//RDWER2 

;Say read error on SHR2 

7$: 

.PRINT 

//BUFFER 

;Print out the contents (1 line, null filled) 


.PRINT 

//PROMPT 

;Say it's time to try companion program 


.TWAIT 

//AREA,//TIME 

;Wait 30 seconds to run other program 


.PURGE 

#0 

;Now, release SHR2 


.GTLIN 

//BUFFER,//PRMPT2 

;Wait for return from virtual line 

;This job will 

be suspended for 

output while gone to virtual line 


.REOPEN 

//AREA, #0, //BLOK 1 

;And get SHRl back 


.READW 

//AREA, #0,//BUFFER 

, //BUFSIZ, #1 ;Read in second block of SHRl 


.PRINT 

//BUFFER 

;And print it to prove status was saved 


.CLOSE 

.EXIT 

#0 

;Release SHRl 

EMTER2: 

MOV 

//SHR2NM, FILNUM 

;Point to alternate file error 

EMTERR: 

MOVB 

@#ERRBYT,R0 

;Get the error type 


DEC 

RO 

;Zero offset 


ASL 

RO 

;Convert to word offset 


.PRINT 

SHRERR(RO) 

;Print the appropriate error message 


.PRINT 

.EXIT 

FILNUM 

;And the file name 

AREA: 

. BLKW 

10 

;EMT arg block area 

BL0K1: 

.BLKW 

5 

jSavestatus area for SHR1.DAT 

FILNUM: 

.WORD 

SHR1NM 

;File name for error message 

TIME: 

.WORD 

0,30.*60. 

;30.sec * 60.tics/sec 

SHRERR: 

: .WORD 

NOTOPN 

;Pointer to EMT error messages 


.WORD 

XSSCHN 



.WORD 

XSSFIL 



.WORD 

AXSCON 



.NLIST 

BEX 


SHRl: 

.RAD50 

/DK. SHRl DAT/ 

;File descriptor for SHR1.DAT 

SHR2: 

.RAD50 

/DK SHR2 DAT/ 

;File descriptor for SHR2.DAT 

SHRFIL: 

: .BYTE 

0,125 

;EMT arg block to declare shared file 


.WORD 

1 

;Exclusive Update access (GETS CHANGED) 

SAVSHR 

.BYTE 

0,122 

;EMT arg block to save shared file status 

N0T0PN 

.ASCII 

/Attempt to share unopened channel/<7><200> 

XSSCHN 

.ASCII 

/Too many channels opened to shared files/<7><200> 

XSSFIL 

.ASCII 

/Too many shared files open/<7><200> 

AXSCON 

.ASCII 

/Attempt to protect already protected shared file/<7><200> 

SHR1NM 

.ASCIZ 

/: SHRl.DAT/ 


SHR2NM 

.ASCIZ 

/: SHR2.DAT/ 
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LKPERR: .ASCIZ 
LKPER2: .ASCIZ 
SVSERR: .ASCIZ 
RDWERR: .ASCIZ 
RDWER2: .ASCIZ 
PROMPT: .ASCII 
.ASCII 
.ASCIZ 
PRMPT2: .ASCII 
BUFFER: .BLKW 


/Lookup error for SHRl.DAT/<7> 

/Lookup error for SHR2.DAT/<7> 

/Error occurred attempting to save SHRl.DAT file status/<7> 
/Error occurred while reading SHR1 .DAT/<(7> 

/Error occurred while reading SHR2.DAT/<7> 

/Go to a virtual line and RUN SHARE2 which attempts /<C15X12> 
/to share the same files (SHRl.DAT, SHR2.DAT)./<15><12> 
/Waiting 30 seconds ./<7> 

/When you have returned, hit RETURN to continue/<200> 

BUFSIZ 


.END START 


See also the example program SHARE2 in the section on saving the status of a 
shared file channel. 

9.2 Saving the status of a shared file channel 


A standard .SAVESTATUS EMT may be used to save the status of a shared file 
channel. If this is done, all blocks that are being held locked in the file 
remain locked until the channel is reopened and the blocks are unlocked (see 
below). 

When using a single channel number to access several shared files it is 
convenient to initially do a .LOOKUP on each file, then declare the file to be 
shared (EMT above), and then do a .SAVESTATUS. The channel being used to 
access the set of files can then be switched from one file to another by doing 
a .PURGE followed by a .REOPEN. However, before doing the .PURGE, TSX-Plus 
must be told that you wish to save the shared—file status pf the file, 
otherwise all locked blocks will be unlocked and the file will be removed from 
the shared-file list. The form of the EMT used to perform this function is: 

EMT 375 

with R0 pointing to the following argument block: 

.BYTE chan,122 

where "chan" is the I/O channel number. The effect of this EMT is to suspend 
the connection between the shared file information table and the I/O channel. 
Any blocks that are currently locked in the file remain locked until the 
channel is reopened to the file (by using a standard .REOPEN EMT). After 
saving a shared file status, the channel may be freed by using a .PURGE EMT. 
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Example: 


•TITLE SHARE2 
.ENABL LC 


; This program cooperates with the example program (SHARED) in the 
; previous section to demonstrate saving of shared file status with 
; the .SAVESTATUS EMT. 


•MCALL .LOOKUP,.PRINT,.EXIT,.READW 
.MCALL .CLOSE,.TWAIT 


ERRBYT =52 
BUFSIZ = 256. 


;EMT error byte 

;Size of disk file block 


START: .LOOKUP //AREA,#0,#SHR1 

BCC 1$ 

.PRINT //LKPERR 
BR 3$ 


;Try to open a file which is access locked 
;Branch if OK 

;Say couldn't get the file 
;Go on to try second file 


1$: MOV //SHRFIL,R0 

EMT 375 

BCC 2$ 

CALL EXPLER 
.PRINT #INSHR1 
.CLOSE // 0 

BR 3$ 


;Point to EMT arg block to 

;Declare file for shared access 

;If got the file, branch to read it 

;Else explain why 

;Say we can't share SHRl 

;Release channel 0 

;Go on to next file 


2 $: 


3$: 


4$: 


5$: 


.READW //AREA,//0,//BUFFER,//BUFSIZ, #0 ;Try to read block 0 of SHRl 
.PRINT //BUFFER ;Display it for kicks 

• CLOSE //0 ;Done with SHRl for the moment 


.LOOKUP //AREA, #0, //SHR2 
BCC 4$ 

.PRINT //LKPER2 
BR 6$ 


;Try to open SHR2 
;Branch if OK 

;Say we couldn't even open it 
;Go on to try SHRl again 


MOV //SHRFIL, R0 

EMT 375 


BCC 5$ 

CALL EXPLER 

• PRINT //AGAIN 

.TWAIT //AREA,//TIME 
BR 4$ 


;Point to EMT arg block to 

;Declare file for shared access 

;Access Input, Update to show lockout 

; though we don't write in this example 

;Branch if we can share it 

;Explain why not 

;Say we will try again later 

;Wait 5 seconds and 

;Try again 


.READW 

.PRINT 

.CLOSE 


//AREA,//0,//BUFFER,//BUFSIZ,//0 ;Read block 0 of SHR2 
//BUFFER ;Prove that we got it 

//0 ;Done with SHR2 
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6$: .LOOKUP 

//AREA, #0,//SHRl 

;Try SHRl again 

BCC 

7$ 


;Branch if it worked 

.PRINT 

//LKPERR 


;Say we couldn't do it 

.EXIT 




7$: MOV 

//SHRFIL, RO 


;Point to EMT arg block to 

EMT 

375 


;Declare shared file 

BCC 

10$ 


;Branch if OK 

CALL 

EXPLER 


;And explain the error 

.PRINT 

//STLLOK 


;Say it was still locked 

BR 

11$ 


;And quit 

10$: .READW 

//AREA,//O,//BUFFER,//BUFSIZ,//! ;Read in block 1 

.PRINT 

//BUFFER 


;And display it 

11$: .CLOSE 

#0 


;Done with SHRl 

.EXIT 




EXPLER: MOVB 

@//E RRBYT.RO 

;Find out why can't share it 

DEC 

RO 


;Convert to zero index 

ASL 

RO 


;Make into word offset 

.PRINT 

SHRERR(RO) 


;Say why we couldn't get it 

RETURN 




.NLIST 

BEX 



AREA: .BLKW 

10 


;EMT arg block 

SHRFIL: .BYTE 

0,125 


;EMT arg block to declare file shared 

.WORD 

5 


;Access Shared, Update 

SHRERR: .WORD 

NOTOPN 


;Shared file error message pointers 

.WORD 

XSSFCH 



.WORD 

XSSFOP 



.WORD 

AXSCON 



TIME: .WORD 

0,5.*60. 


;5.sec * 60.tics/sec 

SHRl: .RAD50 

/DK SHRl 

DAT/ 

;Input file #1 name 

SHR2: .RAD50 

/DK SHR2 

DAT/ 

;Input file #2 name 

NOTOPN: .ASCIZ 

/Cannot share 

unopened file/ 

XSSFCH: .ASCIZ 

/Too many 

channels opened to shared files/ 

XSSFOP: .ASCIZ 

/Too many 

shared files open/ 

AXSCON: .ASCIZ 

/Shared file protected by another job/ 

INSHRl: .ASCIZ 

/On first 

try 

at SHRl.DAT/ 

LKPERR: .ASCIZ 

/Unable to 

lookup SHRl.DAT/ 

LKPER2: .ASCIZ 

/Unable to 

lookup SHR2.DAT/ 

AGAIN: .ASCIZ 

/Can't access 

SHR2.DAT, will try again in 5 seconds/ 

STLLOK: .ASCIZ 

/On second 

try 

at SHRl.DAT/ 

.EVEN 




BUFFER: .BLKW 

BUFSIZ 


;Input read buffer 

.END 

START 
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See also the example program SHARED in the section on opening a shared file, 

9.3 Waiting for a. locked block 

The following EMT can be used to lock a specific block in a file. If the 
requested block is locked by another job, the requesting job will be suspended 
until the desired block becomes available. The form of the EMT is: 

EMT 375 

with RO pointing to the following area: 

.BYTE chan,102 
.WORD block 

where "chan" is the number of an I/O channel that has previously been declared 
to be open to a shared file and "block" is the number of the block in the file 
to be locked. Other blocks in the file which were previously locked remain 
locked. The maximum number of blocks which may be simultaneously held locked 
is specified when TSX-Plus is generated. A block number of -1 (octal 177777) 
can be used to request that all blocks in the file be locked. If several users 
request the same block, access will be granted sequentially in the order that 
the requests are received. 

Errors: 

Code Meaning 

1 Channel is not open to a shared file 

2 Request to lock too many blocks in file 

Example: 


.TITLE LOCKW 
•ENABL LC 

; This program cooperates with the example program (LOCK) in the next 
; section to demonstrate shared file record locking. 

.MCALL .PRINT,.EXIT,.TWAIT,.LOOKUP,.READW,.CLOSE 


ERRBYT = 52 
BUFSIZ = 256. 

START: .LOOKUP //AREA, #0, //SHRl 

BCC 1$ 

. PRINT //LKPERR 
.EXIT 

1$: MOV //SHRFIL, RO 

EMT 375 


;EMT error code byte 
;Words per disk block 

;0pen SHR1.DAT 
;Branch if OK 
;Say bad lookup 


;Point to EMT arg block to 
;Declare shared file 
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BCC 

3$ 

;Branch if OK 


MOVB 

@#ERRBYT,RO 

;Get the error code 


DEC 

RO 

;Make zero index 


ASL 

RO 

;Convert to word offset 


.PRINT 

SHRERR(RO) 

;Print the error message 

2$: 

.CLOSE 

#0 

;Give back the channel 


.EXIT 



3$: 

MOV 

//LOCKW, RO 

;Point to EMT arg block to 


EMT 

375 

;Lock block 0 of SHR1.DAT 


;(Job is suspended until 

block available to be locked) 


BCC 

5$ 

;Branch when block is ready 


CMPB 

0//ERRBYT, #1 

;Which error? 


BHI 

4$ 

;Too many blocks locked? 


.PRINT 

//SFCNOP 

;Wasn't open to shared file! 


BR 

2$ 

;Give up 

4^ 

-CO- 

.PRINT 

//XSLKBL 

;Too many locked blocks in file 



;(Defined by MXLBLK parameter in TSGEN) 


BR 

2$ 

;Give up 

5$: 

. PRINT 

//PROMPT 

;Switch lines to attempt access 


.TWAIT 

//AREA, //SEC20 

;Wait 20 seconds before unlocking 


MOV 

//UNLOCK, RO 

;Point to EMT arg block to 


EMT 

375 

;Unlock a single block 


BCC 

6$ 

;Branch if OK 


.PRINT 

//SFCNOP 

;Wasn't shared file! 


BR 

2$ 

;Give up 

6$: 

.TWAIT 

//AREA,//SEC 10 

;Wait 10 seconds for companion 


MOV 

// CKWSHR.RO 

;Point to EMT arg block to 


EMT 

375 

;Check for writes to shared file 


BCC 

8$ 

;If none, wrap up 


.PRINT 

//CHANGD 

;Say we have new data 


.READW 

//AREA, #0,//BUFFER,//BUFSIZ.//0 ;Get block 0 


.PRINT 

//BUFFER 

;Show current contents block 0 


.READW 

//AREA, //0, //BUFFER,//BUFSIZ,//! ;Get block 1 


.PRINT 

//BUFFER 

;Show contents block 1 


BR 

DONE 


8$: 

.PRINT 

//NOCHNG 

;Say nothing has changed 

DONE: 

.CLOSE 

#0 

;Free up channel 


.EXIT 




.NLIST 

BEX 


AREA: 

.BLKW 

10 

;EMT arg block area 

SHRFIL: 

.BYTE 

0,125 

;EMT arg block to declare shared file 


.WORD 

4 

;Access Shared, Input 

LOCKW: 

.BYTE 

0,102 

;EMT arg block to lock shared file block 


.WORD 

0 

;Block number to be locked 
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UNLOCK: 

CKWSHR: 

SHRERR: 


SHRl: 
SEC20: 
SEC10: 
NOTOPN: 
XSSFCH: 
XSSFOP: 
AXSCON: 
LKPERR: 
SFCNOP: 
XSLKBL: 
CHANGD: 
NOCHNG: 
PROMPT: 


BUFFER: 


.BYTE 

.WORD 

.BYTE 

.WORD 

.WORD 

.WORD 

.WORD 

.RAD50 

.WORD 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.EVEN 

.BLKW 


0,113 

0 

0,121 
NOTOPN 
XSSFCH 
XSSFOP 
AXSCON 
/DK SHRl 
0,20.*60 
0,10.*60. 


;EMT arg block to unlock shared file block 
;Block number to be unlocked 

;EMT arg block to check writes to shared file 
;Shared file error message table 


DAT/ ;File name to be shared 
;20.sec * 60.tics/sec 
;10.sec * 60.tics/sec 
/Channel not opened to shared file/<7> 

/Too many channels opened to shared files/<7> 

/Too many shared files open/<7> 

/File protection access conflict/<7> 

/Unable to open SHRl.DAT/ 

/Can't lock or unlock block not open to shared file/ 

/Can't lock so many blocks in one file/ 

/Data has been written to file. Contents follow:/ 

/Data in file is unchanged/ 

/Block 0 in SHR1.DAT will remain locked for 20 sec/<15><12> 
/Go to another line and RUN TL0CK to test it/<7> 

BUFSIZ 


.END 


START 


9.4 Trying to lock a. block 

This EMT is similar in operation to the previous EMT: it too is used to 

request that file blocks be locked. The difference is that if the requested 
block is already locked by another user the previous EMT suspends the request¬ 
ing program whereas this EMT does not suspend the program but rather returns an 
error code. As above, a request to lock block #-l is treated as a request to 
lock the entire file. If the block is available it is locked for the request¬ 
ing user and no error is reported. The form of this EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE chan,103 
.WORD block 

where "chan" is the number of the I/O channel associated with the file and 
"block" is the number of the block which is to be locked. 
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Code 
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Meaning 


1 Channel is not open to a shared file. 

2 Request to lock too many blocks in file. 

3 Requested block is locked by another user. 

Example: 


.TITLE LOCK 
•ENABL LC 


; This 

program 

cooperates with 

the example program (LOCKW) in the 

; previous section to demonstrate shared file record locking. 


.MCALL 

•PRINT,.EXIT,.WRITW,.TWAIT,.LOOKUP,.CLOSE 

ERRBYT 

= 52 


;Error byte address 

START: 

.LOOKUP 

//AREA, #0, #SHRl 

;Try to open SHR1.DAT 


BCC 

1$ 

;Branch if OK 


.PRINT 

.EXIT 

//LKPERR 

;Say we couldn't open 

1$: 

MOV 

//S HRFIL.RO 

;Point to EMT arg block to 


EMT 

375 

;Declare shared file 


BCC 

3$ 

;Branch if OK 


MOVB 

0//ERRBYT, RO 

;Get error type 


DEC 

RO 

;Convert to zero index 


ASL 

RO 

;Make into word offset 


.PRINT 

SHRERR(RO) 

;Display the error type 

2$: 

.CLOSE 

.EXIT 

#0 

;Release the channel 
;And give up 

3$: 

MOV 

//LOCK, RO 

;Point to EMT arg block to 


EMT 

375 

;Try to unlock block 0 


BCC 

6$ 

;Branch if OK 


CMPB 

0//ERRBYT, #2 

;Which error was it 


BLO 

4$ 

;Wasn't open to share file? 


BEQ 

5$ 

;Request to open too many blocks 


.PRINT 

//WAITNG 

;Block locked by another user 


.TWAIT 

//AREA,//TIME 

;Wait 3 seconds 


BR 

3$ 

;And try again 

4$: 

.PRINT 

//NOPNSF 

;Not open to shared file 


BR 

2$ 

;Give up 

5$: 

.PRINT 

//XSLKBL 

;Too many blocks locked in file 


BR 

2$ 

;Give up 

6$: 

.WRITW 

//AREA.//0, //BUFFER, //BUFSIZ, //0 -.Rewrite block 0 


MOV 

// UNLALL.RO 

;Point to EMT arg block to 
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EMT 375 
• PRINT //GOBACK 


AREA: 
SHRl: 
SHRFIL: 

LOCK: 

UNLALL: 

TIME: 

SHRERR: 


SFCNOP: 

XSSFCN: 

XSSFOP: 

AXSCON: 

LKPERR: 

WAITNG: 

GOBACK: 
NOPNSF: 
XSLKBL: 

BUFFER: 


BR 

•NLIST 
. BLKW 
•RAD50 

• BYTE 

• WORD 

• BYTE 

• WORD 

• BYTE 

• WORD 

• WORD 

• WORD 

• WORD 

• WORD 

.ASCIZ 
•ASCIZ 
•ASCIZ 
•ASCIZ 
•ASCIZ 
•ASCII 

• ASCIZ 
•ASCIZ 
•ASCIZ 
•ASCIZ 

• EVEN 
•ASCII 
•ASCIZ 


2 $ 

BEX 

10 

/DK SHRl 

0,125 

3 

0,103 

0 

0,101 


DAT/ 


;Release all blocks locked by this program 
;Message: done, go back to original line 
;Done 


EMT arg block 
Name of shared file 

EMT arg block to share file on chan 0 

Access Protected, Update 

EMT arg block to lock block on chan 0 

number of block to be locked 

EMT arg block to unlock all blocks on chan 0 

(Only applies to blocks locked by this job) 

3.sec * 60.tics/sec 

File sharing EMT error table 


0,3.*60. 

SFCNOP 
XSSFCN 
XSSFOP 
AXSCON 

/Channel not open to file/<7> 

/Too many channels open to shared files/<7> 

/Too many shared files open/<7> 

/Shared file access conflict/<7> 

/Couldn't open SHRl.DAT/<7> 

/Requested block not available for locking/<15><12> 
/WiJLl try again in 3 seconds/ ^ « 

/Done, log off and go back to original line/ 
/Channel not open to shared file/<7> 

/Attempt to lock too many blocks in file/<7> 


BUFSIZ = <.-BUFFER+l>/2 
•BYTE 0,0 


/(SHRl)This line was written by the program LOCK./ 
/ /<15><12> 

;Number of words to write 
;Safety bumper 


• END 


START 


9.5 Unlocking a. specific block 

The following EMT is used to unlock a specific block in a file. The form of 
the EMT is: 

EMT 375 


with R0 pointing to the following argument block: 

•BYTE chan,113 
•WORD block-number 

where "chan" is the number of the I/O channel opened to the shared file and 
’’block-number" is the number of the block to be unlocked. 
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Errors: 

Code Meaning 

1 Specified channel not opened to a shared file 
Example: 


See the example program LOCKW in the section on waiting for a locked 
block. 

9.6 Unlocking all locked blocks in a file 


The following EMT is used to unlock all blocks held locked in a file. The form 
of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE chan,101 

where "chan" is the I/O channel number open to the shared file. When this EMT 
is executed all blocks previously locked by the user on the shared file are 
unlocked. Blocks locked by the user on other files are not released nor are 
blocks of the same file that are locked by other users. 

Errors: 

Code Meaning 

1 Channel is not open to a shared file. 

Example: 

See the example program LOCK in the section on trying to lock a block. 

9.7 Checking for writes to £ shared file 


The following EMT can be used to determine if any other user has written to a 
shared file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE chan,121 

where "chan" is the I/O channel number opened to the shared file. If no other 
user has written to the file since the file was opened by the user issuing this 
EMT or since that last time this EMT was issued for the file, the carry-flag is 
clear on return from the EMT. 
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Errors: 

Code Meaning 


2 Some other job has written to file since last check 

This EMT is useful when data from a shared file is being held in a program 
buffer. If no other user has written to the file, then the data is still 
valid. However, if the data in the file has been re-written then it must be 
re-read. The usual sequence of operations in this situation is to first lock 
the block whose data is in the program's buffer, then do the EMT to see if the 
file has been written to. If the file has not been modified the data in memory 
is valid and can be used, otherwise the block must be re-read from the file. 

Example: 


See the example program LOCKW in the section on waiting for a locked block. 

9.8 Data caching 

Data caching is a technique provided by TSX-Plus to speed access to files. 
When TSX-Plus is generated a certain number of 512-byte buffer areas may be set 
aside for data caching. These buffer areas are part of the resident system 
data area and are not associated with any particular job. There are two kinds 
of data caching: generalized data caching; and shared-file data caching. Both 
kinds may used automatically with minimal intervention on the part of the 
programmer or operator. Generalized data caching applies to all files on 
MOUNTed devices, while shared-file data caching applies only to files which 
have been declared as shared files. Generally, only one of these types is 
selected during generation of a TSX-Plus system. The following discussion 
applies to shared-file data caching. See the TSX-Plus System Manager's Guide 
for more information on data caching. 

Each time a request is issued to read a shared file, a check is made to see if 
the blocks being read are currently stored in the data cache. If so, the data 
is moved from the cache buffer to the program buffer and no disk I/O operations 
are performed. When data in the cache buffers is accessed, a use count is 
incremented. Periodically, the use counts for all buffers is divided by two. 
If the data blocks being read are not currently in the cache, the data is read 
from the disk into the program buffer and then it is moved into the cache 
buffers with the lowest use count. 

When a write operation is done to a file that is being cached, a check is made 
to see if the data being written is currently stored in the cache. If so, the 
cache buffers are updated. In any case the data is written to the disk. In 
other words, this is a "write-through" cache; the disk file is always updated 
and caching does not improve the performance of "writes". 

All data files that are declared to TSX-Plus for shared access (using EMT 375 
with function code 125) are eligible for data block caching regardless of their 
access protection type. Data caching on a shared file may be disabled by 
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setting bit 8 (octal 400) in the access-code word of the EMT argument block 
when the file is declared for shared access. Data caching is particularly 
effective for COBOL-Plus ISAM files. 
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10. MESSAGE COMMUNICATIONS FACILITIES 


TSX-Plus provides an optional facility that allows running programs to send 
messages to each other. This message communication facility allows programs to 
send messages through named channels, check to see if messages are pending, and 
suspend execution until a message is received. TSX—Plus provides EMTs for each 
of these operations which are described below. 

10.1 Message channels 

Messages are transferred to and from programs by using TSX—Plus Message 
Channels". A message channel accepts a message from a sending program, stores 
the message in a queue associated with the channel and delivers the message to 
a receiving program when requested. Message channels are totally separate from 
I/O channels. 

Each message channel is identified to the sending and receiving programs by a 
one to six character name. The total number of message channels is defined 
when TSX-Plus is generated. The names associated with the channels are defined 
dynamically by the running programs. A message channel is said to be active 
if any messages are being held in the queue associated with the channel or if 
any program is waiting for a message from the channel* When message channels 
become inactive they are released and may be reused. 

Once a message is queued on a channel, that message will remain in the queue 
until some program receives it or the TSX-Plus system is halted. A program may 
exit after queuing a message without affecting the queued message. This allows 
one program to leave a message for another program that will run later. 

10.2 Sending a. message 

The following EMT is used to queue a message on a named channel. If other 
messages are already pending on the channel, the new message is added to the 
end of the list of waiting messages. The sending program continues execution 
after the EMT and does not wait for the message to be accepted by a receiving 
program. During processing of the EMT the message is copied to an internal 
buffer, and the sending program is free to destroy its message on return from 
the EMT. The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 0,104 
.WORD chadr 
.WORD msadr 
.WORD mssiz 

where "chadr" is the address of a six byte field containing the name of the 
message channel (ASCII with trailing blanks if the name is less than six 
characters), "msadr" is the address of the beginning of the message text, and 
"mssiz" is the message length in bytes. 


-163- 















Message Channels 


Errors: 

Code Meaning 

1 All message channels are busy. 

2 Maximum allowed number of messages already in message queues. 

4 The transmitted message is too long. The message is truncated 

to maximum allowed length. 

The system manager may alter parameters during TSX-Plus generation to alle 1 
these error conditions. 

Example; 

.TITLE SNDMSG 
.ENABL LC 


; Demonstrates use of the TSX—Plus EMT to queue a message to the interproc* 
; message communication facility. 

.MCALL .EXIT,.PRINT,.GTLIN 


ERRBYT ■ 

■ 52 

3 

EMT error byte 

START: 

.GTLIN 

#MSGBUF, //MSGPRT 

Get the message to be queued 


MOV 

//MSGBUF.Rl 

Point to beginning of buffer 

1$: 

TSTB 

(RD+ 

Find end of message 


BNE 

1$ 



SUB 

#<MSGBUF+1>,R1 

Determine message length 
accounting for post-increment 


MOV 

Rl,MSGLEN 

Set message length in EMT arg block 


.GTLIN 

//CNLBUF, //CNLPRT 

Get the six character channel name 


MOV 

//MSGBLK, RO 

Point to EMT arg block to 


EMT 

375 

Send message on named channel 


BCC 

9$ 

Branch if no error 


MOVB 

@//ERRBYT,R0 

Which error? 


DEC 

RO 

Zero offset 


ASL 

RO 

Convert to word index 


.PRINT 

.EXIT 

ERRTBL(RO) 

Display the appropriate message 

9$: 

CLRB 

CNLBUF+6 

;Make channel name ASCIZ 

.PRINT 

//DONE OK 

;Inform user message queued 


.PRINT 

.EXIT 

//CNLBUF 

;on channel CNLBUF 


.NLIST 

BEX 


MSGBLK: 

.BYTE 

0,104 

;EMT block: send message on named channel 


.WORD 

CNLBUF 

;Address of channel name 


.WORD 

MSGBUF 

;Address of message 

MSGLEN: 

.WORD 

0 

;Char length of message 
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ERRTBL: 

.WORD 

BSYERR ;Table of send error messages 



.WORD 

FULERR 



.WORD 

0H0H ;Error code 3 not used 



.WORD 

TRNERR 


BSYERR: 

.ASCIZ 

/?SNDMSG-F-Maximum number of messages have been 

queued 

FULERR: 

.ASCIZ 

/7SNDMSG-F-A11 message channels are busy./ 


0H0H: 

.ASCIZ 

/?SNDMSG-F-This is a non-existent error./ 


TRNERR: 

.ASCIZ 

/?SNDMSG-W-Message was too long, truncated./ 


MSGPRT: 

.ASCIZ 

/Message to be queued: / 


CNLPRT: 

.ASCII 

<15><12>/Channel Name (six characters max): /<200> 

D0NE0K: 

.ASCII 

/Message queued on channel /<200> 



.EVEN 



CNLBUF : 

• BLKB 

80. ;First 6 chars to contain file 

name 

MSGBUF: 

• BLKB 

80. ;Message buffer. 



.END 

START 



10,3 Checking for pending messages 

The following EMT is used to receive a message from a named channel if a 
message is pending on the channel. If no message is pending, an error code (3) 
is returned, and the program is allowed to continue execution. The form of the 
EMT is: 


EMT 375 

with R0 pointing to the following argument area: 

•BYTE 0,105 
•WORD chadr 
.WORD msadr 
.WORD mssiz 

where "chadr" points to a field with a six character channel name, "msadr" 
points to the buffer in which the message is to be placed, and mssiz is the 
size of the message buffer (bytes). 

If a message is received, its length (bytes) is placed in R0 on return from the 
EMT. If the message is longer than the message buffer (mssiz), only the first 
part of the message will be received. 

Errors: 

Code Meaning 

3 No message was queued on the named channel. 

4 Message was longer than the receiving buffer. 


-165- 











Message Channels 


Example: 


.TITLE GETMSG 


; Demonstrates use of the TSX-Plus EMT to check for pending messages in the 
; interprocess message communication facility. 


.MCALL .EXIT,.PRINT,.GTLIN 


ERRBYT = 52 


;EMT error byte 


START: .GTLIN 

MOV 
EMT 
BCC 
CMPB 
BEQ 
.PRINT 
.EXIT 

2$: .PRINT 

5$: .PRINT 

.PRINT 
.EXIT 


//CNLBUF , //CNLPRT 
#MSGBLK,R0 
375 
5$ 

0//ERRBYT, #4 

2 $ 

//NOMERR 

//TRNERR 

//PNDMSG 

//MSGBUF 


;Get the channel name 

;Put EMT argument block address in RO 
;EMT to check channel for message 
;Error? 

;Only two errors possible 
;Overflow message buffer? 

;No message 

;Print truncation warning 
;Print message preamble 
;Print actual message 


MSGBLK: .BYTE 
.WORD 
.WORD 
.WORD 
.NLIST 

CNLBUF: . BLKB 
MSGBUF: .BLKB 
.WORD 

CNLPRT: .ASCII 
NOMERR: .ASCIZ 
TRNERR: .ASCIZ 
PNDMSG: .ASCIZ 


0,105 

;GETMSG EMT block 


CNLBUF 

;Channel name buffer address 

MSGBUF 

;Buffer address to 

receive message 

81. 

;Buffer length 


BEX 



80. 

;First 6 chars are 

channel name 

80. 

;Message buffer 


0 

;Insure ASCIZ 



/Channel Name (6 chars): /<200> 

/?GETMSG-F-No messages pending in named channel./ 
/?GETMSG-W-Message truncated/<7> 

/Message pending in named queue is:/ 


.END START 


10.4 Waiting for a message 

The following EMT is used to suspend execution of a program until a message 
becomes available on a named channel. The form of the EMT is: 
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EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,106 
.WORD chadr 
.WORD msadr 
.WORD mssiz 

where "chadr" points to a six byte field containing the channel name, "msadr" 
points to the buffer where the message is to be placed, and "mssiz" is the size 
of the message buffer (bytes). 

The length of the received message (bytes) is placed in RO on return from the 
EMT. 

Errors: 

Code Meaning 

1 All message channels are busy. 

4 Message was longer than the receiving buffer. 

Example: 

.TITLE WATMSG 
.ENABL LC 

; Demonstrate TSX-Plus EMT to wait for a queued message from the 
; interprocess message communication facility. 


.MCALL .EXIT,.PRINT,.GTLIN 


ERRBYT 

= 52 


;EMT error byte 

START: 

.GTLIN 

#CNLBUF, //CNLPRT 

;Get the channel name 


.PRINT 

//WAITNG 

;Explain waiting 


MOV 

//MSGBLK, RO 

;Put EMT argument block address in RO 


EMT 

375 

;EMT to check channel for message 


BCC 

5$ 

;Check for error 


CMPB 

@#ERRBYT,#1 

;Error? 


BHI 

2$ 

;Message truncated 


.PRINT 
.EXIT 

//NOMERR 

;A11 channels busy 

2$: 

.PRINT 

//TRNERR 

;Print truncation warning 

5$: 

.PRINT 

//RCVMSG 

;Print message preamble 


.PRINT 

.EXIT 

//MSGBUF 

;Print actual message 

MSGBLK: 

.BYTE 

0,106 

;WATMSG EMT block 


.WORD 

CNLBUF 

;Channel name buffer address 
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.WORD 

MSGBUF 

;Buffer address to receive message 


.WORD 

81. 

;Buffer length 

CNLBUF: 

.BLKB 

80. 

;Channel name first 6 chars 

MSGBUF: 

.BLKB 

80. 

;Message buffer 


.WORD 

0 

;Insure ASCIZ 


.NLIST 

BEX 


CNLPRT: 

.ASCII 

/Channel Name 

(6 chars): /<200> 

WAITNG: 

.ASCII 

/Waiting for a 

message . . ./<15><12> 


•ASCIZ 

/Go to another 

line and send me something./ 

NOMERR: 

.ASCIZ 

/7WATMSG-F-A11 

message channels are busy./ 

TRNERR: 

.ASCIZ 

/?WATMSG-W-Message truncated./<7> 

RCVMSG: 

.ASCIZ 

/Message received in named queue is:/ 


.END START 
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11. REAL-TIME PROGRAM SUPPORT 


TSX-Plus provides a real-time program support facility that allows multiple 

real-time programs to run concurrently with normal time-sharing operations. 
The basic functions provided by this facility are summarized below. 

1. The ability to map the I/O page into the user's virtual memory region 
so that device status and control registers may be directly accessed 
by the program. 

2. The ability to connect device interrupt vectors to program interrupt 

service routines running at fork level or to program completion 
routines running at user-selectable priority levels with full job 

context. 

3. The ability for a program to lock itself in memory so that rapid 

interrupt response can be assured. 

4. The ability for a program to suspend its execution until an interrupt 
occurs. 

5. The ability to set execution priorities for tasks. 

6. The ability to convert a virtual address within the job's region to a 
physical address for DMA I/O control. 

7. The ability to map a virtual address region to a physical address 

region. 

8. The ability for a program to declare a list of addresses of device 
control registers to be reset when the program exits or aborts 
(.DEVICE EMT). 

Real-time support features are only available if the real-time support facility 
is included in TSX-Plus when the system is generated. 

A program must have operator privilege to use any of the real-time features 
described in this chapter. The real-time facilities are available to both 
normal jobs controlled by time-sharing lines and to detached jobs. Note that 
detached jobs that are specified during system generation for automatic startup 
run with operator privilege; detached jobs started by time-sharing users have 
operator privilege only if the user starting them does. 

11.1 Accessing the I/O page 

A basic facility required by most real-time programs is the ability to access 
the PDP-11 I/O page (160000-177777) which contains the device control and 
status registers. Under TSX-Plus, addresses in this range are normally mapped 
to a simulated RMON or may be used as normal program space. This is done since 
many old programs require direct access to certain system values at fixed 
offsets into RMON, although recent programs should access these values with the 
.GVAL and .PVAL EMTs. TSX-Plus provides several EMTs to deal with mapping of 
the I/O page and accessing locations within it. These are discussed below. 
See Chapter 8 for a discussion of various mapping techniques which may be used 
under TSX-Plus. 
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A TSX-Plus real-time program can access the I/O page in one of two ways: It 

can cause the program's virtual address region in the range 160000 to 177777 to 

be mapped directly to the I/O page so that it can directly access device 
registers; or it can leave the virtual address range mapped to the simulated 
RMON and use a set of EMTs to peek, poke, bit-set and bit-clear registers in 
the I/O page. It is much more efficient to directly access the device control 
registers by mapping the I/O page into the program's virtual address region 
than to use EMTs to perform each access. However, this technique will not work 
if the program must also directly access offsets inside RMON. The correct way 
for a program to access RMON offsets is to use the .GVAL EMT which will work 
even if the I/O page is mapped into the program region. 

11.1.1 EMT to map the I/O page into the program space. 

The following EMT can be used to cause the program's virtual address region in 

the range 160000 to 177777 to be mapped to the I/O page. 

The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 5,140 

The I/O page mapping set up by this EMT remains in effect 8frE±i -the program 
exits, chains, or the EMT described in the next section is used to remap to 
RMON. Note that completion routines and interrupt service routines run with 
the same memory mapping as the main-line code of the job. 

The .GVAL EMT with offset value -8. may be used to determine if PAR 7 is 
currently mapped to the 1/0 page or to the simulated RMON. See the description 
in Chapter 7 of the special use of .GVAL for further information. 


Example: 


TITLE MAPIOP 
ENABL LC 


;Demonstrate TSX-Plus EMTs to map to the 1/0 page and back to RMON 


RMONST = 54 
CONFIG = 300 
RCSR = 176540 
RBUF = RCSR+2 
CTRLC = 3 


;SYSC0M location holding base of RMON 
;Fixed offset into RMON of CONFIG word 
;Serial line RCSR address 
;Line input buffer address 
;Control-C 


.MCALL .PRINT,.EXIT,.TTYOUT,.GVAL 
.GLOBL PRTOCT 


START: CALL SHOMAP 


;Display current PAR 7 mapping 
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CALL 

SHODAT 

;Demonstrate "RMON" mapping 

.PRINT 

//IOPMSG 

;Say we are switching to I/O page mapping 

MOV 

//MAPIOP, RO 

;Point to EMT arg block to 

EMT 

375 

;Map to I/O page 

BCC 

1$ 

;Branch if OK to map 

.PRINT 

//NOPRIV 

;You aren^t allowed to do that 

.EXIT 



1$: CALL 

SHOMAP 

;Display current PAR 7 mapping 

.PRINT 

//TYPE 

;Prompt for input from I/O page 

MOV 

0//RC SR, CSRSAV 

;Save a copy of current CSR 

CLR 

0//RCSR 

;Disable interrupts on serial line 

2$: TSTB 

0//RCSR 

;Is anything available from the line 

BPL 

2$ 

;No, keep checking 

MOVB 

0//RBUF, RO 

;Get the new character 

CMPB 

RO.//CTRLC 

;Should we quit? 

BEQ 

3$ 

;Quit on ~C 

ttyout 


;Display the character 

BR 

2$ 

;And repeat 

3$: MOV 

CSRSAV, 0//RCSR 

;Restore original CSR 

•PRINT 

//GOBACK 

;Say we are returning to original mapping 

MOV 

//MAPMON, RO 

;Point to EMT arg block to 

EMT 

375 

;Map back to simulated RMON 

CALL 

SHOMAP 

;Display current PAR 7 mapping 

CALL 

SHODAT 

;And prove we are back 

.EXIT 



SHOMAP: .PRINT 

//MAPMSG 

;Current mapping preface 

• GVAL 

//AREA, //-8. 

;What is our current PAR 7 mapping? 

ASL 

RO 

;Convert to word offset 

.PRINT 

CURMAP(RO) 

;Show which one it is 

RETURN 



SHODAT: .PRINT 

//CNFGIS 

;Preface config value 

MOV 

@//RMONST,RO 

;Pick up pointer to RMON base 

MOV 

CONFIG(RO),RO 

;Get the current CONFIG value 

CALL 

PRTOCT 

;Display it 

RETURN 



MAPIOP: .BYTE 

5,140 

;EMT arg block to map to I/O page 

MAPMON: .BYTE 

6,140 

;EMT arg block to map to "RMON" 

AREA: .WORD 

10 

;EMT arg block 

CSRSAV: .WORD 

0 

;Save CSR for restoration on exit 

CURMAP: .WORD 

TORMON 

;Current mapping message table 

.WORD 

TOIOPG 


.NLIST 

BEX 


TORMON: .ASCIZ 

/simulated RMON. 

/ 

TOIOPG: .ASCIZ 

”1/0 page.” 


MAPMSG: .ASCII 

/PAR 7 is currently mapped to /<200> 
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CNFGIS: 
TYPE: 
IOPMSG: 
GOBACK: 
NOPRIV: 


.ASCII /Current value of CONFIG word in simulated RMON is /<200> 

.ASCIZ /Characters entered on serial line will be displayed here:/ 
.ASCIZ <12>"Now switching PAR 7 mapping to the I/O page." 

.ASCIZ <15><12>/Returning PAR 7 mapping to simulated RMON./ 

.ASCII /Real-time support not specified during TSGEN or / 

.ASCIZ /user not privileged./ 

.END START 


11.1.2 EMT to remap the program region to the simulated RMON. 

The following EMT can be used to cause the virtual address mapping region of 
the job in the range 160000 to 177777 to be returned to normal mapping if it 
had previously been mapped to the I/O page. The form of the EMT is. 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 6,140 
Example: 

See the example program MAPIOP in the section on mapping the 1/0 page into the 
program space. 


11.1.3 EMT to peek at the I/O page. 

The following EMT can be used to access a word in the I/O page without 
requiring the job's virtual address region to be mapped to the I/O page. (Note 
that the .PEEK and .POKE EMTs can also be used to access parts of the 1/0 page. 
See Chapter 14 for more information on the effects of the .PEEK and .POKE EMTs 
with TSX-Plus.) The form of this EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 1,140 
.WORD address 

where "address” is the address of the word in the I/O page to be accessed. The 
contents of the specified word in the 1/0 page are returned in R0. The 
carry-flag is set on return if real-time support was not included in the 
generation of TSX-Plus or the job does not have operator privilege. Note that 
with this and other EMTs that access the I/O page, if an invalid address is 
specified, an error will result with the message: 

?M0N-F-Kernel mode trap within TSX-Plus 
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.TITLE PEEKIO 
.ENABL LC 


;Demonstrate TSX-Plus EMTs to peek and poke 


into the I/O page 


CTRLC = 3 
RMONST “ 54 
CONFIG = 300 
RCSR = 176540 
RBUF = RCSR+2 


;Control-C 

;Pointer in SYSCOM area to start of "RMON" 
;Fixed offset into "RMON” of config word 
;Serial line RCSR address 
;Line input buffer address 


START: 


1 $: 


2 $: 


3$: 


.MCALL 

•PRINT,.EXIT,. 

TTYOUT,.GVAL 

.GLOBL 

PRTOCT 


CALL 

SHOMAP 

;Display current PAR 7 mapping 

CALL 

SHOCON 

;Demonstrate "RMON'* mapping 

MOV 

//PEEKIO, RO 

;Point to EMT arg block to 

EMT 

375 

;Peek into the I/O page 

BCC 

1$ 

;Branch if OK 

.PRINT 

//NO PR IV 

;You aren^t allowed to do that 

.EXIT 

MOV 

RO.CSRSAV 

;Save a copy of current CSR 

CLR 

POKVAL 

;Want to disable interrupts 

MOV 

//POKE 10, RO 

;Point to EMT arg block to 

EMT 

375 

;Poke a value into the I/O page 

.PRINT 

//TYPE 

;Shouldn't be error if peek worked 
;Prompt for input from I/O page 

MOV 

//PEEKIO, RO 

;Point to EMT arg block to 

EMT 

375 

;Check the RCSR 

TSTB 

RO 

;Is anything available from the line 

BPL 

2$ 

;No, keep checking 

ADD 

//2, PEKADD 

;Point to the receiver buffer 

MOV 

//PEEKIO, RO 

;Point to EMT arg block to 

EMT 

375 

;Get the input character 

CMPB 

RO,#CTRLC 

;Should we quit? 

BEQ 

3$ 

;Quit on ~C 

.TTYOUT 


;Display the character \ 

SUB 

//2, PEKADD 

;Point back to the RCSR \ 

BR 

2$ 

;And repeat \ 

MOV 

CSRSAV,POKVAL 

;Want to restore the original CSR status' 

MOV 

//POKEIO.RO 

;Point to EMT arg block to 

EMT 

375 

;Restore the CSR 


.EXIT 


f 


-173- 










Real-Time Programs 


SHOMAP: 


.PRINT 
• GVAL 
ASL 
.PRINT 
RETURN 


//MAPMSG 
#AREA,#-8. 
RO 

CURMAP(RO) 


{Current mapping preface 
;What is our current PAR 7 mapping? 
{Convert to word offset 
;Show which one it is 


SHOCON: .PRINT //CNFGIS 

MOV @#RMONST,RO 

MOV CONFIG(RO),R0 

CALL PRTOCT 

RETURN 


{Preface config value 
{Pick up pointer to RMON base 
;Get the current CONFIG value 
{Display it 


PEEKIO: 
PEKADD: 
POKE10: 
POKADD: 


POKVAL: 
'AREA: 
CSRSAV: 
CURMAP: 


TORMON: 
TOIOPG: 
MAPMSG: 
CNFGIS: 
TYPE: 
NOPRIV: 


.BYTE 

.WORD 

.BYTE 

.WORD 

• WORD 
.WORD 

• WORD 
.WORD 
.WORD 
.NLIST 
.ASCIZ 
.ASCIZ 
.ASCII 
.ASCII 
.ASCIZ 
.ASCII 
.ASCIZ 
.END 


1.140 
RCSR 

2.140 
RCSR 
0 

10 
0 

TORMON 
TOIOPG 
BEX 

/simulated RMON./ 

"I/O page." 

/PAR 7 is currently mapped to /<200> 

/Current value of CONFIG word in simulated RMON is /<200> 
/Characters entered on serial line will be displayed here./ 
/Real-time support not specified during TSGEN or / 

/user not privileged./ 

START 


;EMT arg block to peek into the I/O page 
{Address to be read 

;EMT arg block to poke into the I/O page 
{Address to be modified 
{Word to be moved to POKADD 
;EMT arg block 

{Save CSR for restoration on exit 
{Current mapping message table 


11.1.4 EMT to poke into the I/O page. _ 

The following EMT can be used to store a value into a cell in the I/O page 
without requiring the job's virtual address region to be mapped to the I/O 
page. The form of the EMT is: 


EMT 


375 


with RO pointing to the following argument area: 

.BYTE 2,140 
•WORD address 
•WORD value 

where "address” is the address of the cell in the I/O page and "value" is the 
value to be stored. The carry-flag is set on return if real-time support was 
not included in the TSX-Plus generation or the job does not have operator 

privilege. 
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Example: 


See the example program PEEKIO in the section on peeking into the I/O page. 
11.1.5 EMT to bit-set a value into the I/O page. 

The following EMT can be used to perform a bit-set (BIS) operation into a cell 
in the I/O page without requiring the job's virtual address region to be mapped 
to the I/O page. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 3,140 
•WORD address 
.WORD value 

where "address" is the address of the cell in the I/O page and "value" is the 
value that will be bit-set into the cell. An error will cause the carry-flag 
to be set on return, indicating that either real-time support was not included 
in the TSX-Plus generation or the job does not have operator privilege. 


Example: 


TITLE BISIO 
ENABL LC 


;Demonstrate TSX-Plus EMTs to bit-set and bit-clear into the I/O page 


CTRLC = 3 
RMONST = 54 
INTNBL =100 
CONFIG = 300 
RCSR = 176540 
RBUF = RCSR+2 


;Control-C 

;Pointer in SYSC0M area to start of "RM0N 
;RCSR interrupt enable bit 
;Fixed offset into "RM0N" of config word 


;Serial line RCSR address 
;Line input buffer address 


MCALL .PRINT,.EXIT,.TTY0UT,.GVAL 


START: CALL SHOMAP 

CALL SH0C0N 


{Display current PAR 7 mapping 
{Demonstrate "RMON” mapping 


MOV //BICI0,R0 

EMT 375 

BCC 1$ 

.PRINT //N0PRIV 
• EXIT 


{Want to clear input interrupts 
{Point to EMT arg block to 
{Clear a bit in the I/O page 
{Branch if OK 

{You aren't allowed to do that 


1 $: 


PRINT //TYPE 


;0K, interrupts should be disabled 
{Prompt for input from 1/0 page 
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2$: MOV 

//PEEKIO, RO 

;Point to EMT arg block to 


EMT 

375 

;Check the RCSR 


TSTB 

RO 

;Is anything available from the 

line 

BPL 

2$ 

;No, keep checking 


ADD 

#2,PEKADD 

;Point to the receiver buffer 


MOV 

//PEEKIO, RO 

;Point to EMT arg block to 


EMT 

375 

;Get the input character 




;Value from peek is returned in 

RO 

CMPB 

RO.//CTRLC 

;Should we quit? 


BEQ 

3$ 

;Quit on ~C 


.TTYOUT 


;Display the character 


SUB 

#2, PEKADD 

;Point back to the RCSR 


BR 

2$ 

;And repeat 


3$: 


;Want to set input interrupts 


MOV 

#BISIO,RO 

;Point to EMT arg block to 


EMT 

375 

;Set a bit in the I/O page 


.EXIT 




SHOMAP: .PRINT 

//MAPMSG 

;Current mapping preface 


.GVAL 

//AREA,//-8. 

;What is our current PAR 7 mapping? 

ASL 

RO 

;Convert to word offset 


.PRINT 

CURMAP(RO) 

;Show which one it is 


RETURN 




SHOCON: .PRINT 

//CNFGIS 

;Preface config value 


MOV 

@//RMONST,RO 

;Pick up pointer to RMON base 


MOV 

CONFIG(RO),RO 

;Get the current CONFIG value 


CALL 

PRTOCT 

;Display it 


RETURN 




PRTOCT: MOV 

R1,-(SP) 

;Save rl-r3 on the stack 


MOV 

R2,-(SP) 

;R0 contains word of interest 


MOV 

R3,-(SP) 



MOV 

#EOW,R2 

;Point to end of 6 char output 

buffer 

MOV 

// 6,R3 

;Set up counter for 6 chars 


1$: MOV 

RO,Rl 

;Set up mask for low 3 bits (Is 

digit) 

BIC 

#177770,R1 

;Get low 3 bits 


ADD 

#'0,R1 

;Convert to ascii 


MOVB 

R1,-(R2) 

;Fill octal digits in from end 


CLC 




ROR 

RO 



ASH 

#-2,RO 

;Shift out bits just converted 


SOB 

R3,l$ 

;Repeat for 6 chars 


.PRINT 

//CHARS 

;Display result at console 


MOV 

(SP)+,R3 

;Restore registers rl-r3 


MOV 

(SP)+,R2 



MOV 

(SP)+,R1 
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RETURN 



PEEKIO: .BYTE 

1,140 

;EMT arg block to peek into the I/O page 

PEKADD: .WORD 

RCSR 

;Address to be read 

BIC10: .BYTE 

4,140 

;EMT arg block to clear a bit in the I/O page 

.WORD 

RCSR 

;Input status register 

.WORD 

INTNBL 

;Interrupt enable mask 

BISIO: .BYTE 

3,140 

;EMT arg block to set a bit in the 1/0 page 

.WORD 

RCSR 

;Input status register 

.WORD 

INTNBL 

;Interrupt enable mask 

AREA: .BLKW 

10 

;EMT arg block 

CSRSAV: .WORD 

0 

;Save CSR for restoration on exit 

CHARS: .BLKB 

6 

;6 char output buffer 

EOW: .WORD 

0 

;Terminator for .PRINT 

CURMAP: .WORD 

T0RM0N 

;Current mapping message table 

.WORD 

T0I0PG 


.NLIST 

BEX 


T0RM0N: .ASCIZ 

/simulated 

RMON./ 

T0I0PG: .ASCIZ 

"I/O page. 

• • 

MAPMSG: .ASCII 

/PAR 7 is currently mapped to /<200> 

CNFGIS: .ASCII 

/Current value of CONFIG word in simulated RMON is /<200> 

TYPE: .ASCIZ 

/Characters entered on serial line will be displayed here:/ 

NOPRIV: .ASCII 

/Real-time 

support not specified during TSGEN or / 

.ASCIZ 

/user not 

privileged./ 

.END 

START 



11.1.6 EMT to do a bit-clear into the I/O page. 

The following EMT can be used to perform a bit-clear (BIC) operation into a 
cell in the I/O page without requiring the job's virtual address region to be 
mapped to the I/O page. The form of the EMT is; 

EMT 375 

with RO pointing to the following argument area: 

•BYTE 4,140 
.WORD address 
•WORD value 

where "address” is the address of the cell in the I/O page and "value" is the 
value to be bit-cleared into the specified cell. An error will cause the 
carry-flag to be set on return, indicating that either real-time support was 
not included in the TSX-Plus generation or the job does not have operator 
privilege. 

Example; 

See the example program BISIO in the section on doing a bit-set into the I/O 
page. 
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11.2 Mapping to a physical memory region 

In certain circumstances, it is desirable to map a portion of virtual memory to 
a specific area in physical memory which is not in the I/O page. Possible 
examples would be ROM memory or an array processor. This mapping is done by 
altering one or more of the Page Address Registers (PARs) for the job. Each 
PAR maps 8192 bytes of memory from the virtual job space into physical memory. 
There are 8 PAR's (8*8192=64Kb). The region of memory mapped through each PAR 
is shown by the table below: 


PAR 

0 

1 

2 

3 

4 

5 

6 
7 


Virtual Region 


000000 

020000 

040000 

060000 

100000 

120000 

140000 

160000 


017777 

037777 

057777 

077777 

117777 

137777 

157777 

177777 


The form of this EMT is: 

EMT 375 

with R0 pointing to the following argument area: 


.BYTE 

17,140 

.WORD 

par-number 

.WORD 

phys-address 

.WORD 

size 

.WORD 

access 


"par-number” is the number of the Page Address Register (PAR) that 
corresponds to the beginning of the program virtual address region that is 
to be mapped. 

"phys-address” is the physical address to which the virtual address is to 
be mapped. The physical address is specified as an address divided by 64 
(decimal). That is, the physical address represents the 64-byte block 
number of the start of the physical region. Note that the physical 
address of any 64-byte block within a 22-bit physical address space can be 
represented in 16 bits. 

"size" is the number of 64-byte blocks of memory to be mapped through the 
virtual region. Each PAR can map up to 128 64-byte blocks of memory. If 
more than 128 blocks are mapped, successively higher PARs are set up to 
map the remainder of the region. 
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"access" indicates if the mapped region is to be allowed read only access 
or both read and write access: 0 = read-only; 1 = read/write. 

This EMT may be used to map any of the PARs to any physical address regions 
desired (even to map PAR 7 to the I/O page). The use of this EMT does not 
affect mapping set up previously for other PARs. If the size parameter is 0 
(zero), all PAR mapping is reset and the normal virtual address mapping for the 
job is restored. 

An error on return indicates either that real-time support was not included in 
the TSX-Plus generation process or that the job does not have operator 
privilege. 

Note that this EMT is not equivalent to the extended memory EMTs used with PLAS 
(Program's Logical Address Space) requests and virtual overlays and virtual 
arrays. See Chapter 8 for a discussion of job environment and the appropriate 
RX-11 manuals for a more complete discussion of PLAS features. 


Example: 


•TITLE MAPPHY 
•ENABL LC 


; Demonstrate TSX-Plus EMT to map to any physical address 


CTRLC 

= 3 


;Control-C 

INTNBL 

= 100 


;Interrupt enable bit 

RCSR 

= 176540 


;Serial line RCSR address 

RBUF 

= RCSR+2 


;Line input buffer address 


.MCALL 

.PRINT, .EXIT,.TTYOUT,.GVAL 

START: 

.PRINT 

//MAPMSG 

;Say we are switching to physical mapping 


MOV 

//MAPPHY, R0 

;Point to EMT arg block to 


EMT 

375 

;Map to physical memory 


BCC 

1$ 

;Branch if OK to map 


.PRINT 

.EXIT 

//NOPRIV 

;You aren't allowed to do that 

1$: 

.PRINT 

// TYPE 

;Prompt for input from I/O page 

BIC 

//INTNBL, 0//RCSR 

;Disable interrupts on serial line 

2$: 

TSTB 

0//RCSR 

;Is anything available from the line 

BPL 

2$ 

;No, keep checking 


MOVB 

0//RBUF ,R0 

;Get the new character 


CMPB 

R0, //CTRLC 

;Should we quit? 


BEQ 

•TTYOUT 

3$ 

;Quit on 'C 

;Display the character 


BR 

2$ 

;And repeat 

3$: 

CLR 

SIZE 

;If .size is 0, original mapping is restored 

MOV 

//MAPPHY, R0 

;Point to EMT arg block to 
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EMT 

375 

;Revoke mapping to physical address 


.EXIT 



MAPPHY: 

• BYTE 

17,140 

;EMT arg block to map to physical memory 


.WORD 

7 

;remap PAR 7 


.WORD 

177600 

;17760000/64. address to map into PAR 7 

SIZE: 

.WORD 

20000 

;size of region to be mapped - full 8kb 


.WORD 

1 

;access 0=read-only, l=read/write 


.NLIST 

BEX 


MAPMSG: 

.ASCIZ 

/PAR 7 

mapping is now directed to top of physical memory. 

TYPE: 

.ASCIZ 

/Characters entered on serial line will be displayed here 

NOPRIV: 

.ASCII 

/Real- 

time support not specified during TSGEN or / 


.ASCIZ 

/user ; 

not privileged./ 


.END 

START 



11.3 Requesting exclusive system control 

The following EMT allows real-time jobs to gain exclusive access to the system 
while they perform time-critical tasks. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 14,140 

The effect of this EMT is to cause the TSX-Plus job scheduler to ignore all 
other jobs, even higher priority jobs - including fixed-high-priority jobs, 
until the real-time job relinquishes exclusive access control. Note that this 
is different (and more powerful) than giving the real-time job a higher 
execution priority because all other jobs are completely prevented from 
executing even if the real-time job goes into a wait state causing the CPU to 
become idle. 

The form of the EMT used to relinquish exclusive system access is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 15,140 

In order to use either of these EMTs, the real-time option must be included 
when the TSX-Plus system is generated and the executing job must have operator 
command privilege. 

The following restrictions apply to a job that has issued an exclusive access 
EMT: 
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1. The job is automatically locked in memory during the time it has 
exclusive access to the system. If you wish to use the TSX-Plus EMT 
that locks a job in the lowest portion of memory, that EMT must be 
executed before calling this EMT to gain exclusive access to the 
system. 

2. The size of the job may not be changed while it has exclusive access 
to the system. 

Exclusive access is automatically relinquished if the job exits or traps but is 
retained if the job chains to another job. 


Example: 



•TITLE 

STEALS 



.ENABL 

LC 


; Demonstrate TSX-Plus EMT to 

obtain exclusive system control 

LEADIN 

= 

35 

;TSX-Plus program controlled terminal 
;option lead-in character. 

JSW 

= 

44 

;Job status word address 

TTSPC 

= 

10000 

;TT special mode bit in JSW 

NOWAIT 

= 

100 

;TT nowait bit in JSW 


.MCALL 

•PRINT,.TTYOUT,.TTYIN,.EXIT 

START: 

MOV 

//TTSPC! NOWAIT 

,@//JSW ;Set TT special mode and nowait 




;bits in the JSW 


.TTYOUT 

//LEADIN 

;And make TSX-Plus understand both 


.TTYOUT 

r S 



.TTYOUT 

//LEADIN 



.TTYOUT 

//'U 



.PRINT 

//MSG 

;Prompt for input 


MOV 

//STEALS, R0 

;Point to EMT arg block to 


EMT 

375 

;Steal exclusive system control 

5 • • • 



;Time critical processing goes here 


.TTYIN 


;Simulated here with terminal input 


MOV 

//LETGO, R0 

;Point to EMT arg block to 


EMT 

.EXIT 

375 

Relinquish exclusive system control 


.NLIST 

BEX 


STEALS: 

.BYTE 

14,140 

;EMT arg block for exclusive system control 

LETGO: 

.BYTE 

15,140 

;EMT arg block to relinquish exclusive control 

MSG: 

.ASCII 

/Other users 

are locked out until you press a key:/<200> 


.END 

START 
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11.4 Locking a. job in memory 

In time-critical real-time applications where a program must respond to an 
interrupt with minimum delay, it may be necessary for the job to lock itself in 
memory to avoid program swapping. This facility should be used with caution 
since if a number of large programs are locked in memory there may not be 
enough space left to run other programs. 

TSX-Plus provides two program locking facilities. The first moves the program 
to the low end of memory before locking it; this is done to avoid fragmenting 
available free memory. This type of lock should be done if the program is 
going to remain locked in memory for a long period of time. However, this form 
of locking is relatively slow since it may involve program swapping. The 
second locking facility simply locks the program into the memory space it is 
occupying when the EMT is executed without doing any repositioning. This EMT 
has the advantage that it is extremely fast but free memory space may be 
non-contiguous. 

The form of the EMT used to lock a program in low memory (re-positioning if 
necessary) is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 7,140 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 

The form of the EMT used to lock a job in memory without repositioning it is: 
EMT 375 

with RO pointing to the following argument area: 

.BYTE 13,140 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 
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11.5 Unlocking a job from memory 

When a job locks itself in memory, it remains locked until the job exits or the 
following EMT is executed. The form of the EMT used to unlock a job from 
memory is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 10,140 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX—Plus generation or the job does 
not have operator privilege. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 


11.6 Suspending/Resuming program execution 

The RT-11 standard .SPND and .RSUM EMTs are used by TSX-Plus real-time jobs to 
suspend and resume their execution. Frequently, a real-time job will begin its 
execution by connecting interrupts to completion routines and doing other 
initialization and then will suspend its execution while waiting for a device 
interrupt to occur. 

The .SPND EMT causes the main-line code in the job to be suspended. Completion 
routines are not affected and execute when interrupts occur. If a completion 
routine executes a .RSUM EMT, the main—line code will continue execution at the 
point following the .SPND when the completion routine exits. Refer to the 
RT-11 Programmer's Reference Manual for further information about the use of 
.SPND and .RSUM. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 
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11.7 Converting a virtual address to a_ physical address 

When controlling devices that do direct memory access (DMA), it is necessary to 
be able to obtain the physical memory address (22-bit) that corresponds to a 
virtual address in the job. Note that a job should lock itself in memory 
before performing this EMT. The form of the EMT is: 


EMT 375 


with RO pointing to the following argument area: 

.BYTE 0,140 

.WORD virtual-address 

.WORD result-buffer 

where "virtual-address'* is the virtual address that is to be converted to a 
physical address and "result-buffer" is the address of a two word area that is 
to receive the physical address. The low-order 16 bits of the physical address 
are stored in the first word of the result buffer and the high-order 6 bits of 
the physical address are stored in bit positions 4-9 of the second word of the 
result buffer. 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX—Plus generation or the job does 
not have operator privilege. 


Example: 


TITLE PHYADD 
ENABL LC 


; Demonstrate TSX-Plus EMT to convert a virtual to a physical address 


MCALL .PRINT,.EXIT 


START: MOV //L0KJ0B , RO 


;Point to EMT arg block to 
;Lock job in memory 
;Continue if OK 
;Explain the problem 
;and quit 

;Say where this program was loaded 

;Get the virtual address 

;and display it to the terminal 


EMT 375 

BCC 1$ 

.PRINT //NO PR IV 
BR 2$ 


1$: .PRINT //STRADD 


MOV //START, RO 

CALL PRTADD 


2$: .EXIT 


PRTADD: MOV RO,VIRADD 


MOV //PHYADD, RO 

EMT 375 


MOV BUFFER,Rl 

MOV <BUFFER+2>,R2 


;Put the virtual address into the arg block 
;Point to EMT arg block to 
;Convert virtual to physical address 
;Retrieve the low address 
;And the high address 
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BIC 

iTC1760,R2 

MOV 

#4,R3 

ASR 

R2 

SOB 

R3,l$ 

MOV 

//CHREND, R4 

MOV 

#8.,R3 

MOV 

R1,R0 

BIC 

#'C7,R0 

ADD 

#'0,R0 

MOVB 

R0,-(R4) 

MOV 

#3 ,R5 

ASR 

R2 

R0R 

Rl 

SOB 

R5,3$ 

SOB 

R3,2$ 

.PRINT 

R4 


RETURN 


;Use only bits 4-9 
;Throw away bits 0-3 

;Point to end of character output buffer 

;Need to convert 8 digits 

;Get a copy of low bits into R0 

;Mask out all but low digit 

;Convert to ASCII 

;Put low digit in output buffer 

;Shift over 3 bits to next digit 

;Low bit of high address 

;into high bit of low address 

;Do all 8 digits 
;Print out the result 


L0KJ0B: .BYTE 
PHYADD: .BYTE 
VIRADD: .WORD 
.WORD 
BUFFER: .WORD 
. BLKB 
CHREND: .WORD 
.NLIST 
NOPRIV: .ASCII 
.ASCIZ 
STRADD: .ASCII 
.END 


13,140 

0,140 

0 

BUFFER 

0,0 

10 . 

0 

BEX 


;EMT arg block to lock job in memory 

;EMT arg block to determine physical address 

;Virtual address to be located 

;Location of 2 word result buffer 

;Will hold low and high physical address 

;Buffer to hold ASCII value of address 

;End of ASCII buffer 


/Real-time not included in TSGEN or user / 
/not privileged./ 

/This program is loaded at START = /<200> 


START 


11.8 Specifying a program-abort device reset list 

The standard RT-11 .DEVICE EMT is used by TSX-Plus real-time jobs to specify a 
list of device control registers to be loaded with specified values when the 
job terminates. This feature is useful in allowing real-time devices to be 
turned-off if the real-time control program aborts. The TSX-Plus .DEVICE EMT 
has the same form and options as the standard RT-11 .DEVICE EMT. See the RT 1 
Programmer's Reference Manual for further information. 

The connection between interrupt vectors and interrupt service routines or 
interrupt completion routines is automatically dropped when a job terminates. 
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11.9 Setting processor priority level 

The following EMT allows a program to set the processor priority level. This 
can be useful in a situation where it is necessary for a real-time job to block 
interrupts for a short period of time while it is performing some critical 
operation. On return from this EMT, the job is executing in user mode with the 
specified processor priority level. The form of the EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE 16,140 
.WORD prio-level 

where "prio-level" should be 7 to cause interrupts to be disabled or 0 to 
reenable interrupts. Interrupts should not be disabled for a long period of 
time or clock interrupts and terminal I/O interrupts will be lost. 

Note that it is not possible to raise the processor priority level by storing 
directly into the processor status word from a real-time program because the 
PDP-11 hardware disallows modification of the PSW by a user mode program even 
if the program has access to the I/O page. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 


11.10 Setting Job Execution Priority 

Jobs may be assigned priority values in the range 0 to 127 to control their 
execution scheduling relative to other jobs. The priority values are arranged 
in three groups: the fixed-low-priority group consists of priority values from 
0 up to the value specified by the PRILOW sysgen parameter; the fixed-high- 
priority group ranges from the value specified for the PRIHI sysgen parameter 
up to 127; the middle priority group ranges from (PRILOW+1) to (PRIHI-1). The 
current values for PRIHI and PRILOW may be determined with the SHOW PRIORITY 
command, or from within a program with a .GVAL request. The following diagram 
illustrates the priority groups: 
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127 


PRIHI — 


PRIDEF — 


PRILOW — 


0 


Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other jobs. A job with a fixed priority is allowed to 
execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 
fixed-low-priority group is intended for use by very low priority background 
tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive, time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed—priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority or jobs 
in the normal job priority range will never be reduced below the value of 
(PRILOW+1). 


Fixed 

high 

priorities 


Normal 

job 

priorities 


Fixed 

low 

priorities 


L-+ 
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The following EMT can be used to set the job priority from within a program. 
Unlike the other real-time EMT's in this chapter, this EMT does not require 
operator privilege. The maximum priority which may be used by a job is set by 
the system manager. The job priority can also be set from the keyboard with 
the SET PRIORITY command. The current job priority, maximum allowed priority, 
and fixed-high— and fixed—low-priority boundaries may be determined with the 
.GVAL request. See the TSX-Plus System Manager's Guide for more information on 
the significance of priority in job scheduling. The form of this EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

•BYTE 0,150 
.WORD value 

where "value" is the priority value for the job. The valid range of priorities 
is 0 to 127 (decimal). The maximum job priority may be restricted through the 
logon mechanism. If a job attempts to set its priority above its maximum 
allowed priority, its priority will be set to the maximum allowed. This EMT 
does not return any errors. 

Example: 


See Chapter 7 for an example of the use of this EMT. 

11.11 Connecting interrupts to real-time jobs 

One of the most important uses for real-time jobs is to service interrupts for 
non-standard devices. TSX-Plus provides three mechanisms for connecting 
user-written real-time programs to interrupts: device handlers, interrupt 
service routines, and interrupt completion routines. Interrupt service 
routines and interrupt completion routines permit jobs to process interrupts 
without the necessity of writing a special device handler. However, there are 
restrictions on the use of these two methods which must be considered when 
deciding the appropriate method for handling special device interrupts. 

The fastest method of handling interrupts is to write a device handler 
(driver). Device handlers execute in kernel mode and provide the fastest 
possible response to interrupts. A device handler is the best choice when 
interrupts occur at a rate which significantly loads the system. Device 
handlers written for use with TSX-Plus should conform to the rules for writing 
device handlers for RT-11XM. 

The second method for processing real-time interrupts is to connect the 
interrupt to a real-time interrupt service routine. The interrupt service 
routine is written as a subroutine in a real-time job; it is not necessary to 
write a separate device handler. Interrupt service routines are connected with 
minimal system overhead and can service interrupts quite rapidly (approximately 
2000 per second on an 11/44). Interrupt service routines are called in user 
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mode but can only execute a limited set of system service calls (EMT's). 
Interrupt service routines can trigger the execution of interrupt completion 
routines to perform additional processing. 

The third method for processing real-time interrupts is to connect the 
interrupt to an interrupt completion routine. Real-time interrupt completion 
routines have access to the full job context and can use most system service 
calls (EMT's), but have more overhead and should not be used for interrupts 
that occur more frequently than 200 times per second. 

The following diagram illustrates the different levels of interrupt processing. 
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Interrupt Processing 
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This diagram shows that there are three "levels'' of interrupt processing. 
Level 1 is entered when a hardware interrupt occurs. In this level the 
processor (hardware) priority is set to 7 which causes other interrupt requests 
to be temporarily blocked. After some brief interrupt entry processing, the 
system performs a .FORK operation which queues a request for processing at fork 
level and then drops the processor priority to 0. At this time another 
hardware interrupt can occur, in which case the cycle will be repeated and 
another request for fork level processing will be placed on the queue. Note 
that if .FORK requests are issued at a sustained high rate, such that numerous 
prior requests cannot be serviced, a system error may eventually occur. 

Level 2 processing is also known as "fork level" processing. This level of 
interrupt processing services requests that were placed on a queue by the .FORK 
operation. Hardware interrupts are enabled during this processing and if any 
other interrupts occur their .FORK requests are placed at the end of the queue. 
Interrupt service requests are processed serially in the order that the 
interrupts occurred. Only two system service calls may be used from service 
routines running at fork level: a request to queue a user completion routine 
for subsequent processing; and the .RSUM EMT. 

Level 3 processing occurs in "job state". That is, the TSX-Plus job execution 
scheduler selects the highest priority job or completion routine and passes 
execution to it. Completion routines run with full job context and may issue 
system service calls (except USR calls) as needed. Completion routines are 
serialized for each job. That is, all other completion routines (including 
higher priority interrupt completion routines) which are scheduled for the same 
job are queued for execution and will not be entered until the current 
completion routine exits. During level 3 processing, interrupts are enabled 
and job execution may be interrupted to process fork level interrupt service 
routines or by higher priority completion routines for other jobs. 

11.11.1 Interrupt service routines. 

Interrupt service routines execute in user mode but require a minimal amount of 
system overhead. When an interrupt is received through a vector which has been 
connected to an interrupt service routine, TSX-Plus executes a .INTEN and a 
.FORK, sets up memory management for the appropriate job, saves the status of 
the floating point unit (FPU) if it is in use, and passes control to the 
interrupt service routine. Using this approach, interrupts may be serviced at 
about 2000 per second on a PDP-11/44. Lower rates should be expected on slower 
processors. 

Several restrictions apply to this method of interrupt processing: 

a) The job must be locked in memory before connecting to the interrupt 
vector and must remain locked in memory as long as the interrupt 
connection is in effect. 

b) The processing done by the interrupt service routine should be brief 
since other interrupts that do .FORKs will be queued until the 
interrupt service routine exits. 
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c) Only two system service calls (EMTs) are valid within a interrupt 
service routine: 

1) A .RSUM EMT may be issued to cause the job's main-line code to 
continue processing if it has done a .SPND. 

2) The TSX-Plus EMT which schedules execution of a completion 
routine. 

Access to the I/O page is possible if the main-line code sets up such mapping 
prior to the interrupt. Registers are undefined on entry to an interrupt 
service routine, and do not have to be preserved by the interrupt service 
routine. 

An interrupt service routine must exit with a RETURN instruction (RTS PC), not 
an RTI. Since interrupt service routines execute at fork level, job scheduling 
ncrt relevant for them. All fork level processing, whether queued for system 
processing or for an interrupt service routine, is executed in the order in 
which the interrupts were received and execute before any completion routines, 
fixed-priority jobs or normal interactive time-sharing jobs. 

The form of the request to connect an interrupt service routine to a vector is. 
EMT 375 

with RO pointing to the following argument block: 

.BYTE 20,140 
.WORD vector-address 
•WORD service-routine 
.WORD 0 

where "vector-address" is the address of the interrupt vector to which the 
service routine is to be connected, and "service-routine" is the address of t e 
entry point of the interrupt service routine. 

The total number of vectors that can be connected either to interrupt service 
routines or interrupt completion routines is determined by the RTVECT parameter 
during TSX-Plus system generation. 

Error: 

Code Meaning 

0 Real time not included or job not privileged 

1 There are no free interrupt control blocks 

2 Some other job is already connected to that vector 

3 Job is not locked in memory 

The association between an interrupt service routine and an interrupt vector 
may be released by the same EMT as used to disconnect an interrupt completion 
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routine. See the section on releasing an interrupt connection later in this 
chapter. 

Example; 

.TITLE INTSVC 
.ENABL LC 


Demonstrate EMT to implement an interrupt service routine 
Simple file capture program. Steal a time-sharing line 
and put everything that comes in on it into a file. 



.MCALL 

.TTYIN,.TTY0UT, 

•EXIT,.PEEK,.POKE,.GVAL,.SCCA 


.MCALL 

•ENTER,.LOOKUP, 

.CSISPC,.WRITE,.PURGE,.CLOSE,.DEVICE 

VECTOR 

= 330 


;Serial line vector 

RCSR 

= 176530 

;Serial line RCSR address 

RBUF 

= RCSR+2 


;Serial input buffer address 

BUFSIZ 

= 256. 


;Size of buffer in words 

INTNBL 

= 100 


;Interrupt enable bit in RCSR 

CTRLC 

= 3 


;ASCII control-C 

CTRLD 

= 4 


;ASCII control-D 

START: 

.GVAL 

//AREA,//-6. 

;See if job is privileged 


TST 

R0 

;1 if priv, 0 if not 


BEQ 

QUIT 

;Immediate exit if not priv 


MOV 

//LOKJOB.RO 

;Point to EMT arg block to 


EMT 

375 

;Lock job in memory 


MOV 

//MAPIO.RO 

;Point to EMT arg block to 


EMT 

375 

;Map PAR7 into the I/O page 

GETFIL: 

MOV 

SP.SPSAVE 

;Save SP prior to CSI call 

1$: 

•CSISPC 

//OUTSPC, //DEFEXT 

, #0 ;Get file specification 


BCS 

1$ 

;Repeat until valid command line 


MOV 

SPSAVE,SP 

;Restore SP, no valid switches 


.ENTER //AREA,//0, //INSPC, //-l ;Open largest possible output file 
BCS 1$ ;0n error, ask for new file 

MOV //BUFFI,BUFPTR ; Initialize buffer pointer 

CLR BLOCK ;Initialize output file block count 

; Set up to accept terminal commands 

; ctrl-c, ctrl-c to abort; ctrl-d to end transmission 
.SCCA //AREA,//TTSTAT ;Disable control-c abort 

MOV //ACTCTD.RO ;Point to EMT arg block to 

EMT 375 ;Activate input on ~D 

; Since we are going to borrow a current time-sharing line, we need 

; to save its vector pointers for later restoration 

MOV 0//RCSR,CSRSAV ;Save old status bits, esp. int. enable 

.DEVICE //AREA,//DEVLST ;Force restoration of RCSR on exit 
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BIC 

//INTNBL, 0//RCSR 

;Disable interrupts until ready 


• PEEK 

//AREA, //VECTOR 

;Get normal vector pointer 


MOV 

RO,VECSAV 

;And save it for later restoration 


.PEEK 

//AREA, //VECTOR+2 

;Get normal priority 


MOV 

RO,VECSV2 

;And save it for later restoration 

; Now 

attach interrupt service 

routine to input vector 


MOV 

// INTSVC.RO 

;Point to EMT arg block to 


EMT 

375 

;Schedule interrupt service routine 

GO: 

BIS 

//INTNBL, 0//RCSR 

;Enable interrupts and wait for input 


.TTYIN 

INBUF 

;Wait for terminal command during transfer 

; Resume here when transfer is 

complete, or want to abort 

WHOA: 

BIC 

//INTNBL, 0//RCSR 

;Disable interrupts (data lost if mistake) 


CMPB 

INBUF, //CTRLC 

;Was it a control-c? 


BNE 

5$ 

;Branch if not 


.PURGE 

#0 

;If CTRL-C, throw away input 


TST 

TTSTAT 

;Did we get double control-c's? 


BEQ 

GETFIL 

;If not, get another file name 


BR 

QUIT 

;If double control-c, then abort 

5$: 

CMPB 

INBUF, //CTRLD 

;Is the transmission done? 


BNE 

GO 

;Branch if not 


CALL 

FINISH 

;Write out remainder of current buffer 


.CLOSE 

#0 

;If done, close out file 

; Done 

or abort 

, restore time-sharing line conditions 

QUIT: 

MOV 

//RE LVEC.RO 

;Point to EMT arg block to 


EMT 

375 

;Release interrupt connection 


.POKE 

//AREA,//VECTOR+2 

,VECSV2 ;Restore old priority 


.POKE 

//AREA,//VECTOR,VECSAV ;And old vector pointer 


.EXIT 


;And done! 


; Interrupt service routine, executes at .FORK level 


ISR: 

MOVB 

0//RBUF ,0BUFPTR 

;Put char in buffer 


INC 

BUFPTR 

;And point to next location 


CMP 

BUFPTR, //BUFF2 

;Which buffer in use? 


BHI 

1$ 

;Branch if already in second 


BLO 

9$ 

;Return if first not full 


MOV 

//BUFF 1, WRTPTR 

;Exact end of buffer 1, point to it 


BR 

2$ 

;Schedule write 

1$: 

CMP 

BUFPTR,//BUFEND 

;Second buffer full yet? 


BLO 

9$ 

;Not yet, return 


MOV 

//BUFFI, BUFPTR 

;Second buffer full, reset pointer 


MOV 

//BUFF2, WRTPTR 

;Point to second buffer for write 

2$: 

MOV 

//SCHWRT.RO 

;Point to EMT arg block to 


EMT 

375 

;Schedule completion routine 
;to write buffer to file 


- 194 - 











Real-Time Programs 


9$: 

TST 

TTSTAT 

;Does mainline want to quit? (~C“C) 


BEQ 

10$ 

;Branch if not 


BIC 

//INTNBL, 0//RCSR 

;If so, disable interrupts 

10$: 

RETURN 


;Wait for another char 




;Note RTS PC, not RTI ! 

; Completion routine to save buffer to file 

CMPRTN: 

.WRITE 

#AREA,#0,R1,#2 56.,BLOCK ;Write buffer to file 


BCC 

1$ 

;Br if no error 


MOVB 

CTRLC,INBUF 

;0n error, set abort flags 


MOV 

#-l,TTSTAT 



JMP 

WHOA 

;Skip •TTYIN, and abort 

1$: 

INC 

BLOCK 

;Point to next output block 


RETURN 



; Routine to complete write of 

last block 

FINISH: 

MOV 

BUFPTR.RO 

;Get current buffer pointer 


MOV 

//BUFF2.R1 

;Point to end of first buffer 


CMP 

R0.R1 

;See which buffer in use 


BLO 

1$ 

;Skip if in first 


ADD 

#2*BUFSIZ,Rl 

;If in second, point to end 

1$: 

CLRB 

(R0)+ 

;Zero out buffer 


CMP 

RO.Rl 

;AL1 the way to the end 


BLO 

1$ 



SUB 

#2*BUFSIZ,R1 

;Now point back to buffer beginning 


CALL 

CMPRTN 

;Call write routine (NOT AS COMPLETION) 


RETURN 



; EMT arg block 

areas 


AREA: 

.BLKW 

10 

;General EMT arg block 

LOKJOB: 

.BYTE 

13,140 

;EMT arg block to lock job in mem 

MAP10: 

• BYTE 

5,140 

;EMT arg block to map 1/0 page to PAR 7 

ACTCTD: 

.BYTE 

0,152 

;EMT arg block to 


.WORD 

D 

;Set activation character 


.WORD 

CTRLD 

;Control-D 

INTSVC: 

.BYTE 

20,140 

;EMT arg block to set up interrupt svc routine 


.WORD 

VECTOR 

;Vector to attach 


.WORD 

ISR 

;Address of Interrupt Service Routine 


.WORD 

0 

;Required 

SCHWRT: 

.BYTE 

21,140 

;EMT arg block to sched compl routine 


.WORD 

CMPRTN 

;Write buffer contents to file 


.WORD 

7 

;Real-time priority (adds to PRIHI) 
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WRTPTR: 

.WORD 

0 


.WORD 

0 

RELVEC: 

.BYTE 

12,140 


• WORD 

VECTOR 

; General storage 

OUTSPC: 

.BLKW 

15. 

INSPC: 

.BLKW 

24. 

DEFEXT: 

.WORD 

0,0,0,0 

SPSAVE: 

.WORD 

0 

BLOCK: 

.WORD 

0 

TTSTAT: 

.WORD 

0 

VECSAV: 

.WORD 

0 

VECSV2: 

.WORD 

0 

DEVLST: 

.WORD 

RCSR 

CSRSAV: 

.WORD 

0 


.WORD 

0 

BUFPTR: 

.WORD 

0 

INBUF: 

.BYTE 

0,0,0,0 

BUFFI: 

.BLKW 

BUFSIZ 

BUFF2: 

.BLKW 

BUFSIZ 

BUFEND: 




.END 

START 

11.11.2 

Interrupt compl* 


;Passed in R1 to compl routine (buffer addr) 

;Required 

;EMT arg block to release interrupt connection 
;Vector to be released 


CSI output file specs 
CSI input file specs 
No default file specs 
Save stack pointer during CSI call 
Output file block counter 
SCCA terminal status word 
Save original vector contents 
and priority 
•DEVICE restoration list 
To hold original value of RCSR 
End of list 

Current input char pointer 
Terminal command buffer 
1 block input buffer 
Second buffer 


The TSX-Plus real-time support facility allows a program to connect a real-time 
interrupt to a completion routine. If this is done, TSX-Plus schedules the 
completion routine to be executed each time the specified interrupt occurs. 


Interrupt completion routines have much greater flexibility than interrupt 
service routines, but require more overhead and are capable of servicing 
interrupts only at a lower rate. Interrupt completion routines run with full 
job context. This allows them to use all system service calls (except to the 
USR). Registers will be preserved between calls to the completion routine. 

Real-time completion routines can service interrupts at rates up to about 200 
interrupts per second. Devices which interrupt at a faster rate should be 
connected through an interrupt service routine or through a special device 
handler. 

The total number of interrupt vectors that can be connected either to interrupt 
completion routines or interrupt service routines is determined by the RTVECT 
parameter during TSX-Plus system generation. It is possible for several 
interrupts to be connected to the same completion routine in a job but it is 
illegal for more than one job to try to connect to the same interrupt. When an 
interrupt completion routine is entered, R0 contains the address of the 
interrupt vector that caused the completion routine to be executed. 
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Real-time completion routines, whether directly connected to an interrupt or 
scheduled with the EMT for that purpose, have an associated job priority. 
These are software priorities, not hardware priorities; all completion routines 
are synchronized with the job and execute at hardware priority level 0. 
Completion routine priorities 1 and larger are classified as "real-time" 
priorities and are added to the system parameter PRIHI to yield the job 
execution priority, unless the resultant priority would exceed 127 in which 
case the priority will be 127. These completion routines will then be 
scheduled for execution whenever there are no executable jobs with a higher 
priority. 

A real-time completion routine for one job will be suspended if an interrupt 
occurs which causes a higher priority completion routine to be queued for 
another job. However, a real-time completion routine for one job will never be 
interrupted by a completion routine for that same job regardless of the 
subsequent completion routine's priority. If additional requests are made to 
trigger the same or different completion routines while a completion routine is 
executing, the requests are queued for the job and are serviced in order based 
on their priority and the order in which they were queued. 

A real-time completion routine is allowed to run continuously until one of the 
following events occurst 1) the completion routine finishes execution and 
returns; 2) a higher-priority completion routine from another job interrupts 
its execution — it is re-entered when the higher-priority routine exits; or 3) 
the completion routine enters a system wait state such as waiting for an I/O 
operation to complete or waiting for a timed interval. If a real time 
completion routine enters a wait state, it returns to the same real-time 
priority when the wait condition completes. 

Real-time completion routines with a priority of 0 are treated slightly 
differently than those with priorities greater than zero. The action taken 
depends on the priority of the main—line job when the completion routine is 
scheduled. If the base priority is equal to or greater than PRIHI, then the 
completion routine is treated just as those with real-time priorities greater 
than zero. That is, the completion routine is assigned a priority of PRIHI 
(PRIHI + the real-time priority of 0). On the other hand, if the base job 
priority is less than PRIHI, then the job is scheduled as a very high priority 
normal (non-interactive) job. The effect of this is that completion routines 
with a real-time priority of 0 and a base job priority less than PRIHI will 
interrupt normal time-sharing jobs, but are time-sliced in the normal fashion 
and lose their high priority if they execute longer than the system parameter 

QUAN1A. 

Jobs that have real-time, interrupt completion routines need not necessarily be 
locked in memory. If an interrupt occurs while the job is swapped out of 
memory, it is scheduled for execution like any other job and swapped in before 
the completion routine is executed. Note, however, that this condition is not 
optimal for timely servicing of interrupts. 
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When a real-time interrupt occurs, a request is placed in a queue to execute 
the appropriate completion routine. If the interrupt occurs again before the 
completion routine is entered, another request is placed in the queue so the 
completion routine will be invoked twice. A TSX-Plus fatal system error occurs 
if an interrupt occurs and there are no free completion routine request queue 
entries. 

When a real-time completion routine completes its execution, it must exit by 
use of a RETURN instruction (RTS PC), not an RTI. 

The form of the EMT used to connect an interrupt to a real-time completion 
routine is: 

EMT 375 

with RO pointing to the following argument area: 

•BYTE 11,140 
.WORD interrupt-vector 
.WORD completion-routine 
•WORD priority 

where "interrupt—vector” is the address of the interrupt vector, completion- 
routine" is the address of the completion routine, and priority is the 
execution priority for the completion routine. 

Error: 

Code Meaning 

0 Real-time support not included or job not privileged 

1 Maximum number of vectors already in use 

2 Some other job is already connected to that vector 

Example: 

.TITLE ATTVEC 
•ENABL LC 

; Demonstrate TSX-Plus EMTs to attach a completion routine to an interrupt 


CTRLC 

ERRBYT 

= 3 
= 52 


;Control-C 

RCSR 

= 176540 


;Serial line RCSR address 

RBUF 

= RCSR+2 


;Line input buffer address 


•MCALL 

.PRINT,.EXIT, 

.TTYOUT,.SPND,.RSUM 

START: 

MOV 

//MAPIOP.RO 

;Point to EMT arg block to 


EMT 

375 

;Map to I/O page 


BCC 

1$ 

;Branch if OK to map 


-198- 










Real-Time Programs 


.PRINT //NOPRIV 
.EXIT 


;You aren't allowed to do that 


I 

If this job were to be resident for a long time, it would be better 
to lock into low memory to avoid memory fragmentation by job swapping. 
However, since this job may have to be swapped now to get into low 
memory, locking into low memory takes longer to execute. 


1$: 

MOV 

//LOKLOW, RO 

;Point to EMT arg block to lock into low mem 

1$: 

MOV 

//LOKJOB.RO 

;Point to EMT arg block to 


EMT 

375 

;Lock the job in memory 


MOV 

#ATTVEC,R0 

;Point to EMT arg block to 


EMT 

375 

;Attach to an interrupt vector 


BCC 

2$ 

;Continue if OK 


.PRINT 

//BADATT 

;Notify can't attach to interrupt 


MOVB 

0//ERRBYT, RO 

;Find out which error 


ASL 

RO 

;Convert to word offset 


.PRINT 

ATTERR(RO) 

;And explain reason for error 


BR 

3$ 

;Go on to unlock and exit 

2$: 

.PRINT 

//TYPE 

;Prompt for input from interrupting device 


. SPND 


;Now wait for an interrupt 

;. . • 



;Resume here on exit from completion code 


MOV 

//RELVEC.RO 

;Point to EMT arg block to 


EMT 

375 

;Release an interrupt vector 

;+ 

; NOTE: 

: Any interrupts through 

this vector after it has been released 

> 

will cause a TSX-Plus 

fatal system error - Unexpected Interrupt. 

3$: 

MOV 

//UNLOKJ.RO 

;Point to EMT arg block to 


EMT 

375 

;Unlock this job from memory 

; + 

.EXIT 



; The 

following 

code will be executed as a completion routine 

; when 

the device attached to 

the vector interrupts. 

y ~~ 



;Enter here when new character is available 

CMPRTN 

: MOVB 

@//RBUF,R0 

;Get the new character 


CMPB 

R0.//CTRLC 

;Should we quit? 


BEQ 

1$ 

;Quit on ~C 


.TTYOUT 

;Display the character 


MOV 

//SETPRI,R0 

;Point to EMT arg block to 


EMT 

375 

;Set processor priority (block interrupts) 




;Time critical processing goes here 

, • . . 

CLR 

PRILEV 

;Set priority back down 
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MOV 

//SETPRI, RO 

;Point to EMT arg block to 

EMT 

375 

;Set processor priority (reenable interrupts) 

BR 

2$ 


1$: .RSUM 


;Return to main-line code 

2$: RETURN 


;Wait for next interrupt (NOTE: Not RTI) 

MAPIOP: .BYTE 

5,140 

;EMT arg block to map to I/O page 

L0KL0W: .BYTE 

7,140 

;EMT arg block to lock job into low mem. 

L0KJ0B: .BYTE 

13,140 

;EMT arg block to lock job in place 

UNLOKJ: .BYTE 

10,140 

;EMT arg block to unlock job from memory 

ATTVEC: .BYTE 

11,140 

;EMT arg block to attach to interrupt 

.WORD 

340 

;Interrupt vector 

.WORD 

CMPRTN 

;Address of completion routine 

.WORD 

7 

;Real-time priority (NOT processor priority!) 

RELVEC: .BYTE 

12,140 

;EMT arg block to release interrupt vector 

.WORD 

340 

;Interrupt vector 

SETPRI: .BYTE 

16,140 

;EMT arg block to set processor priority 

PRILEV: .WORD 

7 

;Desired priority level (modifiable) 

ATTERR: .WORD 

NOPRIV 

;Attach to interrupt error table 

.WORD 

MAXINT 


.WORD 

INUSE 


.NLIST 

BEX 


TYPE: .ASCIZ 

/Characters entered on serial line will be displayed here:/ 

BADATT: .ASCIZ 

/7ATTVEC-F 

-Cannot attach to interrupt./<7> 

NOPRIV: .ASCII 

/Real-time 

support not specified during TSGEN or / 

.ASCIZ 

/user not 

privileged./ 

MAXINT: .ASCIZ 

/Maximum number of interrupts already in use./ 

INUSE: .ASCIZ 

/Another job already connected to interrupt./ 

.END 

START 



11.12 Releasing an interrupt connection 

A connection between an interrupt vector and an interrupt service routine or an 
interrupt completion routine remains in effect until the job exits or the 
following EMT is executed to release the connection. 

Warning: An interrupt through a vector which has been released with this EMT or 
which was connected to a job that has terminated will cause a fatal system 
error: UEI-Interrupt occurred at unexpected location. 

The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 12,140 

.WORD interrupt-vector 
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where "interrupt—vector" is the address of the interrupt vector whose connec 
tion is to be released. An error will cause the carry-flag to be set on 

return, indicating that either real-time support was not included in the 
TSX-Plus generation or the job does not have operator privilege. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 


11.13 Scheduling a_ completion routine 

Real-time programs may schedule a completion routine for execution with a 
special EMT provided for that purpose. This is particularly valuable from 
within interrupt service routines which do not have access to system service 
calls other than this EMT and the .RSUM request. While any program with 
real-time (operator) privilege may issue this request, its primary intent was 
to provide a mechanism for access to system service calls from interrupt 
service routines. The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 


• BYTE 

21,140 

• WORD 

completion-routine 

.WORD 

priority 

.WORD 

Rl-value 

.WORD 

0 


where "completion-routine" is the address of the entry point of the completion 
routine that is being started, "priority” is the real-time priority level for 
the completion routine being started, and "Rl—value is a value to be placed in 
Rl on entry to the completion routine. 

Completion routines scheduled in this manner follow the same rules as for 
interrupt completion routines described above, except that they are scheduled 
as a result of the EMT call rather than in response to an interrupt. 

Example: 

See the example program INTSVC in the section on connecting interrupts to 
real-time jobs/ interrupt service routines. 
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11.14 Adapting real-time programs to TSX-Plus 

The following points should be kept in mind when converting an RT-11 real-time 

program for use under TSX-Plus. 

1. The I/O page (160000-1777 77) is not directly accessible to the program 
unless the program executes the TSX-Plus real-time EMT that maps the job s 
virtual region to the I/O page. 

2. If the program's virtual region 160000 to 177777 is mapped to the I/O 
page, the program must use .GVAL to access offsets in the simulated RM0N. 

3. Real-time interrupts are connected to interrupt service routines and 
interrupt completion routines by use of the TSX—Plus real-time EMT for 
that purpose. The program should not try to connect interrupts by storing 
into the interrupt vector cells. 

4. The .PROTECT EMT is a no-op under TSX-Plus and always returns with the 
carry-flag cleared. 

5. Interrupt service routines and completion routines connected to real-time 
interrupts should exit by use of a RTS PC instruction rather than RTI. 

6. Programs that require very rapid response to interrupts should use the 
interrupt service routine method and must lock themselves in memory. 

7. Real-time interrupts must not occur unless an interrupt service routine or 
completion routine is connected to the interrupt. If a real-time 
interrupt occurs with no associated interrupt service or completion 
routine, a fatal TSX-Plus system error (UEI) occurs and the "argument 
value" displays the address of the vector of the interrupt. 

8. A higher priority real-time completion routine for one job will interrupt 
a lower priority completion routine being executed by another job but will 
not interrupt a lower priority completion routine being executed by the 
same job. 

9. A real-time completion routine running at priority 1 or above is not 
time-sliced and will lock out all lower priority jobs until it completes 
its processing or enters a wait state. 
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( 

TSX-Plus provides a facility that allows one or more shared run-time systems or 
data areas to be mapped into the address space of multiple TSX Plus time 
sharing jobs. There are two primary uses of this facility: 

1. Memory space can be saved by having multiple jobs that use the same 
run-time system access a common copy rather than having to allocate 
space within each job for a copy. 

2. Programs can communicate with each other through the use of a common 
shared memory region to which all of the communicating jobs have 
direct access. 

To use this facility, information about all of the shared run-time systems must 
be declared when the TSX-Plus system is generated. During system initializ¬ 
ation the shared run-time system files are opened and read into memory. These 
shared run-time systems remain in memory as long as the system is running and 
are never swapped out of memory even if there are no jobs actively using them. 

The EMTs described below can be used to associate one or more shared run-time 
systems with a job. When such an association is made, a portion of the job's 
virtual memory space is mapped to allow access to part or all of one or more 
run-time systems. 

12.1 Associating a run-time system with a job 

The following EMT is used to associate a shared run-time system with a job. 
The form of the emt is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,143 
.WORD name-pointer 

where "name-pointer" is the address of a two-word cell containing the six 
character name of the shared run-time system in RAD50 form. This name 
corresponds to the file name which was specified for the run-time system when 
TSX-Plus was generated. If the name pointer value is zero, the effect of the 
EMT is to disassociate all shared run-time systems from the job and to 
re-establish normal memory mapping for the job. 

If the run-time system whose name is specified with this EMT is not recognized, 
the carry—flag is set on return with an error code of 1. 

The effect of this EMT is to associate a particular shared run-time system with 
the job. However, this EMT does not affect the memory mapping for the job or 
make the run-time system visible to the job; that is done by the EMT described 
below. If some other run-time system has been previously mapped into the job's 
region, that mapping is unaffected by this EMT. Thus it is possible to have 
multiple run-time systems mapped into the job s region by associating and 
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mapping them one at a time into different regions of the job's virtual memory 
space. 


Example: 

.TITLE USERTS 
.ENABL LC 

; Demonstration of TSX-Plus EMT to map to a shared run-time region 



.MCALL 

.PRINT,.EXIT 


PARI 

= 20000 


;Base address of PAR 1 window 

START: 

MOV 

//USERTS, R0 

;Point to EMT arg block to 


EMT 

375 

;Associate a shared run-time region 


BCC 

1$ 

;Error? 


.PRINT 

.EXIT 

//NOSHRT 

;Can't find named shared run-time 

1$: 

MOV 

//MAPRTS, RO 

;Point to EMT arg block to 


EMT 

375 

;Map to shared run-time system 

2$: 

CALL 

@//<PARl+200> 

;JSR to entry point in shared region 
;which prints some data from there. 


CLR 

SHRNAM 

;Undeclare any shared run-times 


CLR 

<SHRNAM+2> 



MOV 

//USERTS, RO 

;Point to EMT arg block to 


EMT 

375 

;Dissociate all shared regions 

; • • • 

.EXIT 


;Go on with other processing 

USERTS: 

.BYTE 

0,143 

;EMT arg block to associate 


.WORD 

SHRNAM 

;Pointer to file name 

SHRNAM: 

.RAD50 

/RTCOM / 

;Shared region file name 

MAPRTS: 

.BYTE 

1,143 

;EMT arg block to map shared region 


.WORD 

1 

;Map PAR 1 


.WORD 

0 

;0ffset into region 


.WORD 

1000/64. 

;Size of region (64. byte blocks) 


.NLIST 

BEX 


NOSHRT: 

.ASCIZ 

/Can't find the 

shared run-time system./<7> 


.END 

START 



The example program RTCOM declared in the above program was defined during 
TSX-Plus system generation with the RTDEF macro as follows: 

RTDEF <SY RTCOM SAV>,RW,1 


and the shared program itself was: 

.TITLE RTCOM 
.ENABL LC 

; Demonstration shared run-time file 
; (Position Independent Code.) 

.MCALL .PRINT 
.NLIST BEX 

.PSECT RTCOM,I ;RTDEF in TSGEN specifies 
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;skip 1 block so default start address of 1000 is OK 


START: 

.ASCII 

/This data was 

produced by the / 


.ASCIZ 

/RTC0M shared 

run-time region./ 


. = START + 200 

;Entry point for shared code 

ENTRY:: 

MOV 

PC,R0 

;Find out where we are 


SUB 

#<.-START>,R0 

;Point back to data area 


•PRINT 

R0 

;Display what is there 


RETURN 


;And go back to MAIN 


.END 

ENTRY 



12.2 Mapping a run-time system into a job's region 

Once a shared run-time system has been associated with a job by use of the 
previous EMT, the run-time system (or a portion thereof) can be made visible to 
the job by mapping it into the job's virtual address region. The form of the 
EMT to do this is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 1,143 
.WORD par-region 
•WORD run-time-offset 

'— - .WORD mapped-size ... « 

The "par—region" parameter is a number in the range 0 to 7 that indicates the 
Page Address Register (PAR) that is to be used to access the run-time system. 
The PAR number selects the region of virtual memory in the job that will be 
mapped to the run-time system. The following correspondence exists between PAR 
numbers and virtual address regions within the job: 

PAR Address Range 


0 000000 - 017777 

1 020000 - 037777 

2 040000 - 057777 

3 060000 - 077777 

4 100000 - 117777 

5 120000 - 137777 

6 140000 - 157777 

7 160000 - 177777 

The "run-time-offset" parameter specifies which portion of the run-time system 
is to be mapped into the PAR region. The "run-time-offset" specifies the 
number of the 64-byte block within the run-time system where the mapping is to 
begin. This makes it possible to access different sections of a run-time 
system at different times or through different regions. 
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The "mapped-size” parameter specifies the number of 64-byte blocks to be 
mapped. If this value is larger than can be contained within a single PAR 
region, multiple PAR regions are automatically mapped as necessary to contain 
the entire specified section of the run-time. 

If an error is detected during execution of the EMT, the carry-flag is set on 
return with an error code of 1 to indicate that there is no run-time system 
associated with the job. 

This EMT only affects the mapping of the PAR region specified in the argument 
block (and following PAR's if the size so requires). It does not affect the 
mapping of any other PAR regions that may previously have been mapped to a 
run-time system. Thus a job may have different PAR regions mapped to different 
sections of the same run-time system or to different run-times. Real-time 
programs may map PAR 7 to the I/O page and also map other PAR regions to shared 
run-time systems. 

The memory size of a job is not affected by the use of the shared run-time 
control EMTs. That is, mapping a portion of a job's virtual address space to a 
shared run-time system neither increases nor decreases the size of memory 
occupied by the job. If a job's size is such that a portion of its normal 
memory is under a PAR region that is mapped to a run-time system, that section 
of its normal memory becomes inaccessible to the job as long as the run-time 
system mapping is in effect, but the memory contents are not lost and may be 
re-accessed by disassociating all run-time systems from the job. 

Note that any of the PAR regions may be mapped to a run-time system including 
PAR 7 (160000-177777). 

Example: 


See the example program USERTS in the section on associating a run-time system 
with a job. 
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13. TSX-Plus PERFORMANCE MONITOR FEATURE 


TSX-Plus includes a performance analysis facility that can be used to monitor 

the execution of a program and determine what percentage of the run time is 

spent at various locations within the program. During performance analysis, 
TSX-Plus examines the program being monitored when each clock tick occurs (50 
or 60 times per second) and notes at what location in the program execution is 
taking place. Once the analysis is completed the TSX-Plus performance 
reporting program (TSXPM) can be used to produce a histogram showing the 
percentage of time spent at various locations during the monitored run. 

There are three steps involved in performing a performance analysis on a 
program: 

1. Use the MONITOR command to begin the analysis. 

2. Run the program to be monitored. 

3. Run the TSXPM program to print a histogram of the result. 


13.1 Starting a performance analysis 

The first step in doing a performance analysis is to use the MONITOR keyboard 
command to tell TSX-Plus that a performance analysis is to be done on the 
program that will be run next. The form of the MONITOR command is: 

MONITOR base-address,top-address[,cell-size]/switches 

where "base-address" is the lowest address in the region to be monitored, 
"top-address" is the highest address in the region to be monitored, and 
"cell-size" is an optional parameter that specifies the number of bytes of 
address in the region being monitored to be grouped together into each 
histogram cell. If the "cell-size" parameter is not specified, TSX-Plus 
calculates the cell size by dividing the number of bytes in the region being 
monitored (base-address to top-address) by the total number of histogram cells 
available (specified when TSX-Plus is generated). This gives the finest 
resolution possible. The only available switch is "/I" which causes I/O wait 
time to be included in the analysis. If this switch is not specified, only CPU 
execution time is included in the analysis. A link map of the program should 
be available to determine the addresses in the program that are appropriate to 
monitor. 

Examples: 

. MONITOR 1000,13000/1 
. MONITOR 20000,40000,10 
. MONITOR 2000,6000 

The effect of the MONITOR command is to set up parameters within TSX-Plus which 
will be used to monitor the next program run. It does not actually begin the 
analysis, so there is no rush in running the program to be monitored. Once the 
MONITOR command has been issued, the program to be monitored is run by using 
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the standard "RUN” or "R" commands. If a program being monitored does a .CHAIN 
to another program, the analysis continues and the times reported will be the 
composite of the programs run. 

Only one user may be doing a performance analysis at a time. This is because 
the performance analysis histogram buffer is a common memory area that may not 
be in use by more than one user at a time. An analysis is in effect for a user 
between the time the MONITOR command is issued and the TSXPM program is run to 
display the results of the analysis. Running the TSXPM program terminates the 
performance analysis and allows other users to perform analyses. Note that 
space for the performance analysis data buffer must be reserved when TSX-Plus 
is generated. 

If the program to be monitored is overlayed and the region to be monitored is 
in the overlay area, the analysis technique is more complex. In this situ¬ 
ation, the EMTs described below must be used to control the performance 
analysis as overlay segments are run in the segment being monitored. 

13.2 Displaying the results of the analysis 

After the program being monitored has exited and returned control to the 
keyboard monitor, the TSXPM performance reporting program is used to generate a 
histogram of the time spent in the region being monitored. The TSXPM program 
is started by typing ”R TSXPM"; it responds by printing an asterisk ("*"). In 
response to the asterisk, enter the file specification for the device/file 
where the histogram is to be written. An optional switch of the form "/M:nnn" 
may be specified following the file specification. This switch is used to 
specify the minimum percentage of the total run-time that a histogram cell must 
contain in order to be included in the display. If this switch is not 
specified, the default cut-off percentage is 1%. 

After receiving the file specification, TSXPM prompts for a title line. Enter 
a line of text which will be printed as a page title in the histogram file. 
Press RETURN if you wish no title. 

The next item of information requested by TSXPM is a set of base offset values. 
The base offset values are optional. Base offsets are useful in the situation 
where you have several modules making up a program being monitored and you want 
the addresses displayed on the performance analysis histogram to be relative to 
the base of each module. You may specify up to 10 offset values. Each offset 
value is specified as an offset module number (in the range 0 to 9) followed by 
a comma and the base address of the module (see example below). If offset 
values are specified, TSXPM determines in which module each cell of the 
histogram falls and displays the address as a module number and offset within 
the module. After you enter all desired module offsets, enter RETURN without a 
value. 

After the base offset values are entered, the histogram will be produced and 
written to the specified device and file. After the histogram is generated, 
TSXPM prints the asterisk prompt again, at which point you may enter the name 
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of another device/file and produce the histogram again or you may type 
control-C to return to the keyboard monitor. 

Example use of TSXPM: 

.R TSXPM 
*LP:/M:5 

Title: PERFORMANCE ANALYSIS OF EIGENVALUE CALCULATION 
Base offsets: 

> 1,1000 

>2,2134 

>3,5212 

> 

(Histogram is produced at this point) 

* <CTRL-C> 

The histogram produced by TSXPM consists of one line per histogram cell. Each 
line contains the following information: 1) the base module offset number (if 
offsets were specified); 2) the address range covered by the histogram cell 
(relative to the module base if base offsets were used); 3) the percentage of 
the total execution time spent at the address range covered by the histogram 
cell; 4) a line of stars presenting a graphic representation of the histogram. 

13.3 Performance monitor control EMT^s 

For most applications the method described above can be used to do a perform¬ 
ance analysis. However, in special cases (such as analyzing the performance of 
an overlayed program) it is necessary to have more explicit control over the 
performance analysis feature as a program is running. The following set of 
EMTs may be used to control a performance analysis. 

13.3.1 Initializing a pe rformance analysis. 

This EMT is used to set up parameters that will control a performance analysis. 
It does not actually begin the analysis. The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument block: 

.BYTF 0,136 
•WORD base-address 
.WORD top-address 
.WORD cell-size 
•WORD flags 

where "base-address" is the address of the base of the region to be monitored, 
"top-address" is the address of the top of the region to be monitored, and 
"cell-size" is the number of bytes to group in each histogram cell. If 0 
(zero) is specified as the cell size, TSX-Plus calculates the cell size to use 
by dividing the number of bytes in the region being monitored (top-address 
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minus base-address) by the number of cells available in the histogram data area 
(specified when TSX-Plus is generated). The "f lags'* parameter is used to 
control whether or not I/O wait time is to be included in the analysis. If a 
value of 1 is specified as the "flags" parameter, I/O wait time is included in 
the analysis; if a value of 0 (zero) is specified, I/O wait time is not 
included in the analysis. 

Errors: 

Code Meaning 

0 Performance analysis being done by some other user. 

1 Performance analysis feature not included in TSX-Plus generation. 

Example: 

.TITLE DEMOPA 
.ENABL LC 


; Demonstrate use of TSX-Plus EMT's to initialize, start, stop, and 
; terminate a performance analysis 



•MCALL 

.EXIT,.PRINT,.LOOKUP,.READW,.CLOSE,.TTYOUT 


.GLOBL 

PRTOCT 

;Display an octal word in R0 

ERRBYT 

= 52 


;EMT error byte 

SPACE 

= 40 


;ASCII 'space' 

STAR 

= 52 


;ASCII 'asterisk/ 

START: 

MOV 

//INITPA.RO 

;Point to EMT arg block to 


EMT 

375 

;Initialize the performance analysis 


BCC 

5$ 

;No error 


MOVB 

@#ERRBYT,R0 

;Which error? 


ASL 

R0 

;Convert to word offset 


.PRINT 

INIERR(RO) 

;Print the error message 


.EXIT 


;And depart this world of woe. 

5$: 

MOV 

#STRTPA,R0 

;Point to EMT arg block to 

EMT 

375 

;Start the performance analysis 


BCC 

10$ 

;No error 


.PRINT 

//STRERR 

;Start error 


.EXIT 


;and depart. 

10$: 




; Dummy 

section 

of code to do some I/O 

and computation for analysis 

BEGIN: 

.LOOKUP 

//AREA, //0, //FILNAM 



MOV 

//10,R1 


; Disk I/O 



1$: 

.READW 

//AREA, //0, //BUFFER, //256. 

,#0 


SOB 

Rl,l$ 



.CLOSE 

#0 
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; Terminal I/O 

.PRINT //BUFFER 
; Compute bound 



MOV 

#123456,R3 

2$: 

MOV 

#12345,RO 


CLR 

R1 


DIV 

#345,RO 

ENDB: 

SOB 

R3,2$ 

NCELLS 

= «ENDB-BEGIN>/2> 


MOV 

#STOBLK,RO 


EMT 

375 


BCC 

15$ 


.PRINT 

.EXIT 

#ST0ERR 

15$: 

MOV 

#HALBLK,RO 


EMT 

375 


BCC 

20$ 


MOVB 

@#ERRBYT,R0 


ASL 

R0 


. PRINT 

.EXIT 

HLTERR(RO) 

20$: 

TST 

HALFLG 


BPL 

25$ 


.PRINT 

#0VRWRN 

25$: 

BIT 

#1,HALFLG 


BEQ 

30$ 


.PRINT 

#I0WN0T 

; Print 

a histogram of the performance 

30$: 

CLR 

R3 

35$: 

CMP 

HSTTBL(R3),#64. 


BHI 

40$ 


ADD 

#2, R3 


CMP 

R3,#<2*NCELLS> 


BLE 

35$ 


BR 

50$ 

40$: 

CLR 

R3 

45$: 

CLC 



ROR 

HSTTBL(R3) 


ADD 

#2,R3 


CMP 

R3,#<2*NCELLS> 


BLE 

45$ 


BR 

30$ 

50$: 

.PRINT 

#HSTMSG 


MOV 

#BEGIN,R2 


CLR 

R3 

55$: 

MOV 

R2,R0 


;Number of cells in histogram 

;Point to EMT arg block to 

;Stop the performance analysis 

;Check for error return 

;Only one error - PA not initialized 

;and leave. 

;Put HALTPA block address in RO 

;Terminate the performance analysis 

;Check for errors 

;Get error type 

;Convert to word offset 

;Print out proper error message 

;And depart. 

;Check HALTPA return flag 
;No cell overflow? 

;Issue overflow warning 
;I/0 time included? 

;Skip message if not 

;Print I/O wait time included msg 

analysis 

;Set histogram cell counter 
;Normalize the table for 64. longest 
;Too many counts? 

;Point to next cell 
;End of table? 

;No, repeat 

;A11 cells less than 64. counts now 
;Re-init. histogram cell counter 
;Divide each cell count by 2 

;Point to next cell 
;End of table? 

;No, repeat 

;Go check all cells again 

;Caption histogram 

;Set first analyzed address 

;Init. cell counter 

;Get ready to print it out 
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60$: 

65$: 


INITPA: 


STRTPA: 

STOBLK: 

HALBLK: 


PRMBUF: 

HALFLG: 

HSTTBL: 

HSTEND: 

AREA: 

BUFFER: 

FILNAM: 

INIERR: 

HLTERR: 


INPRG: 
NOGEN: 
NO PA : 
TOSMAL: 
STRERR: 
STOERR: 
OVRWRN: 
IOWNOT: 
OKDONE: 
HSTMSG: 
CRLF: 


CALL PRTOCT 
.TTYOUT //SPACE 
MOV HSTTBL(R3),R1 

BEQ 65$ 

.TTYOUT //STAR 
SOB R1,60$ 

.PRINT //CRLF 

CMP (R2)+,(R3)+ 

CMP R3,//<2*NCELLS> 
BLE 55$ 

.EXIT 


;Display analyzed address 
;For formatting 
;Get address use counter 
;No stars on 0 count 
;Print a for each count 

;Go to next line 

;Point to next address and count 
;End of histogram? 

;No, display next cell 
;Else done. 


.BYTE 0,136 

.WORD BEGIN 

.WORD ENDB-2 

.WORD 2 

.WORD 1 

.BYTE 1,136 

•BYTE 2,136 

•BYTE 3,136 

.WORD PRMBUF 

.WORD HSTTBL 

.WORD <HSTEND-HSTTBL> 

.BLKW 3 

.WORD 0 

.BLKW <2*NCELLS>+2 


;EMT arg block for perform, analysis 
;Start analysis address 
;End analysis address 
;Count 1 address in each cell 
;Include 10 wait time. 

;Start Performance Analysis EMT block 
;EMT arg block to stop perf. analysis 
;EMT arg block to release analysis 
;PA parameter buffer address 
;Histogram Table buffer address 
;Histogram Table buffer length 
;PA four word parameter buffer 
;PA return flags 
;Histogram table 


.BLKW 10 
.BLKW 256. 

.WORD 0 

.RAD50 /DK DEMOPAMAC/ 

.WORD INPRG 
.WORD NOGEN 
.WORD NOPA 
.WORD TOSMAL 
.NLIST BEX 

.ASCIZ /?INITPA-F-Performance analysis being done by another user./ 

.ASCIZ /7INITPA-F-Performance analysis feature not genned./ 

.ASCIZ /?HALTPA-F-This job is not doing a performance analysis./ 
.ASCIZ /?HALTPA-F-Area provided for histogram table too small./ 

.ASCIZ /7INITPA-F-Performance analysis not initialized yet./ 

.ASCIZ /?STOPPA-F-Performance Analysis has not been initialized./ 
.ASCIZ /?HALTPA-W-Some histogram cell(s) overflowed during analysis./ 
.ASCIZ I HALTPA-I-I/0 wait time included in performance analysis.! 
•ASCIZ / STOPPA-S-Performance Analysis stopped./ 

.ASCIZ /Address Frequency/ 

.ASCIZ <15><12><200> 

.END START 


;EMT arg block area 
;Data input buffer 
;Make sure buffer is ASCIZ 
;Read this file 
;Initialize PA error table 

;HALTPA Error message table 
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13.3* 2 Starting a. performance analysis . 

This EMT is used to begin the actual collection of performance analysis data. 
The previous EMT must have been executed to set up parameters about the 
performance analysis before this EMT is called. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 1,136 

The carry-flag will be set on return from this EMT if performance analysis has 
not been initialized yet. 

Example: 


See the example program DEMOPA in the section on initializing a performance 
analysis. 

13.3.3 Stopping a. performance analysis. 

The following EMT can be used to suspend the data collection for a performance 
analysis. The data collection can be restarted by using the start-analysis EMT 
described above. This EMT could, for example, be used to suspend the analysis 
when an overlay module is loaded that is not to be monitored. The start- 
analysis EMT would then be used to re-enable the data collection when the 
overlay of interest is re-loaded. The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 2,136 

The carry flag will be set on return from this EMT if performance analysis has 
not been initialized yet. 

Example: 


See the example program DEMOPA in the section on initializing a performance 
analysis. 

13.3.4 Terminating a_ performance analysis. 

This EMT is used to conclude a performance analysis. It has the effect of 
returning into a user supplied buffer the results of the analysis and releasing 
the performance analysis feature for other users. The form of this EMT is: 
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EMT 375 

with RO pointing to the following argument block: 

.BYTE 3,136 
.WORD parameter-buffer 
•WORD histogram-buffer 
.WORD buffer-size 

where "parameter-buffer" is the address of a 4 word buffer into which will be 
stored some parameter values describing the analysis that was being performed, 
"histogram-buffer" is the address of the buffer that will receive the histogram 
count values, and "buffer-size" is the size (in bytes) of the histogram buffer 
area. 

The values returned in the parameter buffer consist of the following 4 words: 
1) base address of the monitored region; 2) top address of the monitored 
region; 3) number of bytes per histogram cell; 4) control and status flags. 
The control and status flags are a set of bits that provide the following 
information: 

Flag Meaning 


1 I/O wait time was included in the analysis. 

100000 Some histogram cell overflowed during the analysis. 

The data returned in the histogram buffer consists of a vector of 16-bit binary 
values, one value for each cell in the histogram. The first value corresponds 
to the histogram cell that starts with the base address of the region that was 
being monitored. 

Errors: 

Code Meaning 

0 This job is not doing a performance analysis. 

1 Area provided for histogram count vector is too small. 

Example: 

See the example program DEMOPA in the section on initializing a performance 
analysis. 
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14.1 System service call (EMT) differences between RT-11 and TSX-Plus 

The following list describes the differences in the way TSX-Plus implements 
some RT-11 system service calls (EMTs). If an EMT is not listed, it provides 
the same functions as described in the RT-11 Programmer's Reference Manual. 


.ABTIO 

Action depends on setting of IOABT system parameter. If IOABT is set 
to 1 then .ABTIO operates the same as RT-11 and calls handler abort 
entry points. If IOABT is set to 0 then .ABTIO does not call handler 
entry points, but instead does a .WAIT on all channels. The default 
method of handling I/O abort requests is chosen during TSX-Plus 
system generation with the IOABT parameter. The I/O abort handling 
method may also be changed while TSX—Plus is running with the SET 10 
[NO]ABORT keyboard command. 

. CDFN 

User jobs may not define more than 16 channels. If a .CDFN EMT is 
done, all channels are purged if a .CHAIN is done. If .CDFN is not 
done, channels are not purged across a chain. 

.CHCOPY 

Not implemented. 

.CNTXSW 

Not implemented. 

.DEVICE 

Operator privilege is required to use this EMT. 

.FETCH 

Returns in RO the address specified for the handler load area. All 
TSX-Plus device handlers are resident, hence the .FETCH EMT performs 
no operation. If the device handler specified was not loaded during 
TSX-Plus initialization, then an error code of 0 is returned. 

.FORK 

May be used in device handlers but not in user jobs. 

.GTJB 

The job number returned in word 1 of the result area is two times the 
TSX-Plus line number. That is, the first line specified in the 
system generation will be number 2, the second 4, etc. Words 8 
through 12 of the result area are not altered by this EMT. 

.HRESET 

Action depends on setting of IOABT system generation parameter. If 
IOABT is set to 1 then .HRESET calls handler abort entry points. If 
IOABT is set to 0 then .HRESET does not call handler entry points but 
instead does a .WAIT on all channels. Messages queued on named 
message channels are not canceled. Otherwise, this EMT operates the 
same as under RT—11. 

.INTEN 

May be used in device handlers but not in user jobs. 

.LOCK 

The TSX-Plus file management module (USR) is always "resident" and 
the .LOCK EMT is ignored. 

.MTxxxx 

Multi-terminal control EMT's (.MTIN, .MTOUT, .MTPRNT, etc.) are not 

supported. 
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Restrictions 


.MTPS 

•MWAIT 

.PEEK 

.POKE 

.PROTECT 

• QSET 

• RCVD 

.RELEAS 
.SETTOP 

. SDAT 

. SFPA 

.SDTTM 

.SRESET 


The processor priority level may not be changed from user mode, hence 
this macro performs no operation. TSX-Plus provides a special 
real-time EMT to set the processor priority. 

Not supported. See the chapter that describes inter-job message 
communication. 

Non-privileged jobs may use .PEEK to access cells within the 
simulated RMON (addresses 160000 to 160626) although the .GVAL EMT is 
a recommended alternative. Jobs with operator privilege may use 
.PEEK to access the 1/0 page or low memory cells in kernel space. 
References to addresses in the virtual address range of the simulated 
RMON (160000 to 160626) are always directed to RMON rather than the 
1/0 page. 

Non-privileged jobs may use .POKE to access cells within the 
simulated RMON (addresses 160000 to 160626) although the .PVAL EMT is 
a recommended alternative. Jobs with operator privilege may use 
.POKE to access the 1/0 page or low memory cells in kernel space. 
References to addresses in the virtual address range of the simulated 
RMON (160000 to 160626) are always directed to RMON rather than the 
I/O page. 

Not supported. See the chapter on real-time programming for 
information about how to connect an interrupt to a TSX-Plus job. 

TSX-Plus uses an internal pool of 1/0 queue elements for all jobs 
hence it is not necessary to define additional 1/0 queue elements in 
order to perform overlapped I/O. The .QSET EMT is ignored. 

Not supported. See the chapter that describes inter-job message 

communication. 

This EMT is ignored. Refer to .FETCH. 

Returns the job limit in R0 but does not actually expand or contract 
the allocated job region. The job region allocation can be changed 
by use of the MEMORY keyboard command or the TSX-Plus specific EMT 
for this purpose. 

Not supported. See the chapter that describes inter-job message 

communication. 

This EMT functions the same as RT-11. It must be used if a job is 
going to use the floating-point unit. 

Operator privilege is required to use this EMT. 

Messages queued on named message channels are not canceled. 
Otherwise, this EMT operates the same as under RT-11. 
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.SYNCH May be used in handlers but not in user jobs. When used in a 

handler, the number of the TSX-Plus job that is being synchronized 
with must be stored in word 2 of the SYNCH block. 

.TLOCK This EMT is ignored. 

.TTINR Only honors bit 6 in the Job Status Word (TCBIT$) if a SET TT NOWAIT 

command has been issued, or the running program has send the "U" 

program controlled terminal option to the system, or the program was 
R[UN] with the /SINGLECHAR switch. 

.UNLOCK This EMT is ignored. 

.UNPROT Not supported. See the chapter on real-time programming for 

information about how to connect an interrupt to a TSX-Plus job. 

A full list of RT-11 compatible and TSX-Plus specific EMTs is included in 
Appendix D. The list indicates the level of support TSX-Plus provides for each 
RT-11 compatible EMT. 

14.2 Programs Not Supported by TSX-Plus 

Most programs which run under RT—11 will run under TSX-Plus without change. 
However, a modified version of ODT ("TSODT"—supplied with TSX—Plus) must be 
used to debug programs under TSX-Plus. 

The FORMAT program may not be used under TSX-Plus. 

The BATCH RT-11 facility is not supported by TSX-Plus. 

The logical subset disk feature is provided internally to TSX-Plus and 
therefore does not use the LD pseudo-device handler. 

The single line editor feature is provided as an optional system overlay region 
with TSX-Plus and does not use the SL pseudo-device handler. 

The VM handler supplied with TSX-Plus was written specially for use with 
TSX-Plus and is not the same as the DEC VM handler. 

The QUEUE package (QUEUE and QUEMAN) is not supported by TSX-Plus. 

The RESORC utility is not supported. 
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Appendix A — SETSIZ PROGRAM 

The SETSIZ program can be used to store into a SAV file information about how 

much memory space should be allocated for the program when it is executed. 

SETSIZ can also be used to set the "virtual job" flag in the job status word 
(JSW) for a program. 

There are three ways that the amount of memory allocated to a job can be 
controlled: 

1. The TSX-Plus EMT with function code 141 (described in Chapter 7) may be 

used by a running program to dynamically set the job's size. 

2. If a size is specified in a SAV file (by use of the SETSIZ program) the 

specified amount of memory is allocated for the program when it is 
started. 

3. If no size is specified in the SAV file, the size specified by the last 
MEMORY keyboard command is used. 

Note that the .SETTOP EMT does not alter the amount of memory space allocated 
to a job but can be used by a running program to determine the amount of memory 
allocated. 

The effect of the SETSIZ program is to store into location 56 of block 0 of the 
SAV file the number of K-words of memory to allocate for the program when it is 
run (the LINK "/K:n" switch can also be used to do this). This value has no 
effect when the SAV file is run under RT—11 but causes TSX—Plus to allocate the 
specified amount of memory when starting the program. 

If a size value is specified in a SAV file, it takes precedence over the size 
specified by the last MEMORY keyboard command. The TSX-Plus EMT with function 
code 141 may still be used to dynamically alter the memory allocation while the 
program is running. 

Most programs allocate memory in two ways: 1) a static region that includes 
the program code and data areas of fixed size; 2) a dynamic region that is 
allocated above the static region — usually the .SETTOP EMT is used to 
determine how much dynamic space is available to the program. The size of the 
static region for a program is fixed at link time. If the program is overlayed 
the static region includes space for the largest overlay segment as well as the 
program root. Location 50 in block 0 of the SAV file is set by the linker to 
contain the address of the highest word in the static region of the program. 

The amount of memory space to allocate for a SAV file can be specified to the 
SETSIZ program in either of two ways: 1) as the total amount of memory for the 
program which includes space for the static plus dynamic regions; or 2) as the 
amount of memory for the dynamic region only, in which case SETSIZ automatic¬ 
ally adds the size of the static region. 
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SETSIZ 


A.1 Running the SETSIZ program 

The SETSIZ program is started by use of the command 
.R SETSIZ 

it responds by printing an asterisk to prompt for a command line. The form of 
the command line is: 

*filespec/switch:value 

Where "filespec" is a file specification of the standard form dev:name.ext with 
the default device being ,, DK”and the default extension being "SAV". 

If a file specification is entered without a switch, the effect is to cause 
SETSIZ to display information about the size of the SAV file; the SAV file is 
not altered. 

SETSIZ also displays the following status message if the SAV file is flagged as 
being a virtual image. 

Virtual-image flag is set 

The virtual message is displayed if either of the following two conditions 
exist for the SAV file: 

1. Bit 10 (mask 2000) is set in the job status word (location 44) of the 
SAV file. 

2. Location 0 of the SAV file contains the RAD50 value for "VIR". 

These are the same two conditions that cause TSX-Plus to recognize the SAV file 
as being a virtual image when it is started. 

Examples: 


.R SETSIZ 
*TSTPRG 

Base size of program is 22Kb 
Size of allocation space is 28Kb 
*SY:PIP 

Base size of program is 10Kb 
Size of allocation space is 22Kb 
*PR0G1 

Base size of program is 31Kb 
No allocation size specified in SAV file 
Virtual-image flag is set 
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Appendix B ~ DIBOL TSX-Plus SUPPORT SUBROUTINES 


A set of subroutines is provided with TSX—Plus to perform DIBOL record locking 
and message transmission functions. DIBOL ISAM files are not supported by 
TSX-Plus. These subroutines may not be used with DBL, which provides most of 
their functionality separately. Note that if these TSX-Plus features are to be 
used, they must be enabled when the TSX-Plus system is generated. 

B.l Record locking subroutines 

The record locking subroutines coordinate access to a common file being shared 
and updated by several TSX-Plus users. The five subroutines parallel the 
operation of the DIBOL statements: OPEN, CLOSE, READ, WRITE and UNLOCK. The 
normal DIBOL I/O statements cannot be used to perform record locking under 
TSX-Plus. 

Opening the f ile 

The first subroutine is used to open a shared file in update mode. The form of 
the call is: 

XCALL FOPEN(chan,devlbl,errflg) 
where 

chan = A decimal expression that evaluates to a number in the range 

1-15. This is the channel number used in associated calls to FREAD, 
FWRIT, FUNLK and FCLOS subroutines. 

devlbl = The name of an alphanumeric literal, field or record that 
contains the file specification in the general form: dev:filnam.ext 

The file size must not be specified with the file name. An optional 
”/W” switch may be appended to the file name to cause the "WAITING 
FOR dev:file" message to be printed. 

errflg = A numeric variable capable of holding at least two digits into 
which is stored an indication of the result of the FOPEN call. The 
following values are returned: 

Value Meaning 

0 No error. File is open and ready for access. 

17 File name specification is invalid. 

18 File does not exist or channel is already open. 

72 Too many channels are open to shared files. 

Re-gen TSX-Plus and increase the value of MAXSFC parameter. 

73 Too many shared files are open. 

Re-gen TSX-Plus and increase the value of MAXSF parameter. 

The FOPEN subroutine should only be used to open files that will be updated by 
several users. The normal DIBOL OPEN READ/WRITE sequence should be used for 
other files. Several files may be opened for update by calling FOPEN with 
different channel numbers. The ONERROR DIBOL statement does not apply to these 
record locking subroutines. Instead the "errflg" argument is used to indicate 
the outcome of the operation. 
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DIBOL Subroutines 


Locking and reading a record 

The FREAD subroutine is used to lock and read a record. The form of the call 
is: 

XCALL FREAD(chan,record,rec #,'T' or 'W',errflg) 

where 

chan = Decimal expression in the range 1-15 that identifies a channel 
previously opened by FOPEN. 

record = Name of the record or alphanumeric field in which the record 
read is to be placed. 

rec // = Decimal expression that specifies the sequence number of the 
record to be read. This value must be between 1 and the total number 
of records in the file. 

'T'/'W' = If 'T' is specified as the fourth parameter, FREAD will return a 
value of 40 in errflg if the requested record is locked by some other 
user. If 'W' is specified, FREAD will wait until the record is 
unlocked by all other users and will never return the record-locked 
error code. 

errflg = Decimal variable into which is stored one of the following 
values: 

Value Meaning 

0 No error. Record has been locked and read. 

1 End-of-file record has been read. 

22 I/O error occurred on read or channel is not open. 

28 Invalid record number (possibly beyond end of file). 

40 Record locked by another user. 

(Only returned if 'T' is specified as fourth argument.) 

71 Channel was not opened by calling FOPEN. 

72 Request to lock too many blocks in file. 

Re-gen TSX-Plus and increase value of MXLBLK parameter. 

The FREAD subroutine functions like the DIBOL READ statement. However, whereas 
the DIBOL READ statement always returns an error code (40) if the requested 
record is locked, FREAD offers the user a choice: If 'T' is specified as the 

fourth argument to FREAD, a code of 40 will be returned in errflg if the record 

is already locked. If 'W' is specified as the fourth argument and the record 

is locked, FREAD does not return an error code, but rather waits until the 

requested record is unlocked. It is much more efficient to wait for a locked 
record by using the 'W' option rather than re-executing the FREAD with the 'T' 
option. It may be desirable to perform the first FREAD using the 'T' option. 
If the record is locked a ’’WAITING FOR RECORD...” message can be displayed on 
the user's console and another FREAD can be issued with the W option to wait 
for the record. On return from this FREAD the "WAITING” message can be erased. 
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Note that although record locking is requested on a record-by-record basis, the 
actual locking is done on a block—within—file basis. (A block contains 512 
characters). The result of this is that a record is locked if any record 
contained in the same block(s) as the desired record is locked. 

Once a record is locked and read using FREAD, the record remains locked until 
the program performs one of the following operations: 

1. Issues an FWRIT to the channel from which the record was read, 

2. Issues another FREAD to the channel. 

3. Issues an FUNLK to the channel. 

4. Issues an FCLOS to the channel. 

5. Terminates execution by use of the STOP statement or because of an 
error. 

The same set of rules that apply to the DIBOL READ statement apply to FREAD. 
Writing a record 

The FWRIT subroutine is called to write a record to a shared file. The form of 
the call is: 

XCALL FWRIT(chan,record,rec #,errflg) 
where 

chan = Channel number associated with the file. 

record = Name of the record or alphanumeric field that contains the 
record to be written. 

rec # = Decimal expression that specifies the sequence number of the 
record to be written. 

errflg = Decimal variable into which is stored one of the following 
values. 

Value Meaning 


0 No error. 

22 I/O error occurred during write or channel is not open. 

28 Bad record number specified. 

The FWRIT subroutine writes the indicated record to the file then unlocks any 
blocks that were locked by the program. FWRIT appends a <CR><LF> to the end of 
the written record as does the DIBOL WRITE statement. The rules for the DIBOL 
WRITE statement also apply to FWRIT. 
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Unlocking records 

The FUNLK subroutine is used to unlock records that were locked by calling 
FREAD. The form of the call is: 

XCALL FUNLK(chan) 

chan = Channel number. 


Closing a sha red file 

The FCLOls subroutine is called to close a channel that was previously opened to 
a shared file by calling FOPEN. The form of the call is: 

XCALL FCLOS(chan) 

chan = Channel number. 

FCLOS unlocks any locked records and closes the file. Other users accessing 
the file are unaffected. After calling FCLOS, the channel may be reopened to 
some other file. 


Record Locking Ex ample 

In the following example a program performs the following functions: 

1. Opens a shared file named "INV.DAT" on channel 2. 

2. Reads a record whose record number is stored in RECN into the field 
named ITEM and waits if the record is locked by another user. 

3. Updates the information in the record. 

4. Rewrites the record to the same position in the file. 

5. Closes the shared file. 

XCALL F0PEN(2,'INV.DAT',ERRFL) 

XCALL FREAD(2,ITEM,RECN,'W',ERRFL) 

;<update record> 

XCALL FWRIT(2,ITEM,RECN,ERRFL) 

XCALL FCLOS(2) 


Modifying programs for TSX-Plus 

It is a straightforward process to modify DIBOL programs to use the TSX- ius 
record locking subroutines. OPEN, CLOSE, READ, WRITE, and UNLOCK statements 
that apply to shared files must be replaced by the appropriate subroutine 
calls. Error conditions must be tested by IF statements following the 
subroutine calls rather than by using the ONERROR statement. 


B.2 Message communication subroutines 


Three subroutines are included in the DIBOL support package to allow programs 
to transfer messages to each other. When running under TSX-Plus these 
subroutines must be used instead of the DIBOL SEND and RECV statements. 
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Message Channels 

Messages are transferred to and from programs by using . TSX-Plus Message 
Channels". A message channel accepts a message from a sending program, stores 
the message in a queue associated with the channel and delivers the message to 
a receiving program that requests a message from the channel. Message channels 
are totally separate from I/O channels. 

Each active message channel has associated with it a one to six character name 
that is used by the sending and receiving programs to identify the channel. 
The total number of message channels is defined when TSX-Plus is generated. 
The names associated with the channels are defined dynamically by the running 
programs. A message channel is said to be "active" if any messages are being 
held in the queue associated with the channel or if any program is waiting for 
a message from the channel. When message channels become inactive they are 
returned to a free pool and may be reused by another program. 

The DIBOL SEND command directs a message to a program by using the name of the 
receiving program. Under TSX-Plus, a sending program transmits a message using 
an arbitrary channel name. Any program may receive the message by using the 
same channel name when it requests a message. 

Sending a Mes sage _ _ rr L 

The MSEND subroutine is called to queue a message on a named channel. If other 
messages are already pending on the channel the new message is added to the end 
of the list of waiting messages. The form of the call is: 

XCALL MSEND(chan,message,errflg) 


alphanumeric literal or variable that contains the 
channel name (1 to 6 characters). 

alphanumeric or decimal literal, field or record that contains 
the message to be sent. 

Decimal variable into which will be stored one of the following 
values: 

Value Meaning 


0 No error. Message has been sent. 

1 All message channels are busy. (Re-gen TSX-Plus and 
increase the value of MAXMC parameter). 

2 Maximum allowed number of messages are being held in 
message queues. (Re—gen TSX-Plus and increase the value 
of MAXMSG parameter). 

Note that the maximum message length that may be transferred is defined during 
system generation by the MSCHRS parameter. If a message longer than this is 
sent, only the first part of the message will be delivered. 


where 
chan = 

message = 

errflg = 
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Checking for Pending Messages 

The MSGCK subroutine may be called to determine if any messages are pending on 
a named channel. The form of the call is: 

XCALL MSGCK(chan,message,errflg) 

where 

chan = alphanumeric literal or variable that contains the name of the 
channel (1 to 6 characters). 

message = alphanumeric or decimal field or record where the received 
message is to be placed. 

errflg = decimal variable into which will be stored one of the following 
values: 

Value Meaning 

0 No error. A message has been received. 

3 No message was queued on the named channel. 

If a received message is shorter than the receiving message field the remainder 
of the field is filled with blanks. If the message is longer than the field, 
only the first part of the message is received. 

Waiting for a. Message 

The MSGWT subroutine is used by a receiving program to suspend its execution 
until a message is available on a named channel. It is much more efficient for 
a program to wait for a message by calling MSGWT rather than repeatedly calling 
MSGCK. The form of the call is: 

XCALL MSGWT(chan,message,errflg) 

where the arguments have the same meaning as for MSGCK, and the following 
values may be returned in errflg. 

Value Meaning 

0 No error. A message has been received. 

1 All message channels are busy. 
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ITTexample a program sends a message to another program b, using 
a message channel named -SORT'; and then waits for a reply to come back through 
a message channel named REPLY • 


XCALL MSEND('SORT','DK:PAYROL.DAT',ERRFL) 

IF(ERRFL.NE.O)GO TO ERROR 

XCALL MSGWT('REPLY',MSGBF,ERRFL) 

IF(ERRFL.NE.0)GO TO ERROR 


B.3 Using the subroutines 

The subroutines described above are part of the MACRO program called 
"DTSUB.MAC". Once assembled, the object file for DTSUB (DTSUB.OBJ) may be 
linked with DIBOL programs that use the record locking or message facilities. 
An example of a LINK command is shown below. 


.R LINK 

*PROG=PROG,DTSUB,DIBOL 


B.4 Miscellaneous functions 


Determining the TSX-Plus line number 

The TSLINsubroutine can be called to determine the number of the 
timesharing line from which the program is being run. Real lines are 
consecutively starting at 1 in the same order they are spec:ified when 
is generated. Detached job lines occur next and virtual lines 

last. 


TSX-Plus 

numbered 

TSX-Plus 

numbered 


The form of the call of TSLIN is: 


XCALL TSLIN(lnum) 

where "lnum” is a numeric variable capable of holding at least two digits into 
which is stored the TSX-Plus line number value. 
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Appendix C ~ FILTIM PROGRAM 


In addition to the date of creation of a file, TSX-Plus also stores file 
creation times in device directories. At the time a file is closed, the 
current time of day is automatically stored in the sixth word of the directory 
entry for that file. Under RT-11, this word is unused for permanent files and 
contains the job and channel number for tentative file entries. In order to 
represent the time as a positive 16-bit value, the time is converted to an 
integer representing the number of 3 second intervals since midnight. For 
example, if a file were closed at 11:13:22, then the sixth word of the 
permanent directory entry for that file would contain 13467 (32233 octal). 

11 hr * 60 min/hr * 60 sec/min / 3 sec/interval = 13200 

13 min * 60 sec/min / 3 sec/interval = 260 

22 sec / 3 sec/interval = 7 


13467 

An EMT to obtain file directory information, including file creation times is 
provided by TSX-Plus. An EMT is also provided to set the file creation time 
value into file directory entries. See Chapter 7 for information on use of 
these EMTs. 

The DIR utility provided with RT-11 does not interpret file creation time 
information as set by TSX-Plus, so a utility program (FILTIM) is provided with 
TSX-Plus to obtain this information. The FILTIM program should be copied from 
the distribution medium to the system device (SY:). It may then be run either 
explicitly (R FILTIM) or implicitly as a system program (FILTIM). Although 
FILTIM does not accept wildcard file specifications, it will accept up to 6 
file specifications. The default device is "DK" and the default extension is 
"MAC”. A device specification also applies to subsequent file specifications 
which do not explicitly include a device. Files created under RT-11 or before 
this feature was implemented in TSX-Plus will have a creation time of 00:00:00. 


Example: 


.FILTIM CKACT.TPRMAN.TXT,MAN :CHI3.DPS,APPC.DPS,RKO:FILTIM 
DK:CKACT.MAC 
DK:TPRMAN.TXT 
MAN:CHI3.DPS 
MAN:APPC.DPS 
RKO:FILTIM.MAC 


3P 

31-May-83 

00:00:00 

184 

835 

17-Jul-83 

22:15:33 

14226 

35 

18-Jul-83 

08:31:42 

3570 

5 

18-Jul-83 

15:54:48 

3605 

23 

18-Jul-83 

11:24:57 

4240 


Note that the default device "DK” is used for CKACT and is carried over to the 
next file specification, and that the default file type is "MAC . The logical 
device "MAN" is used for the next two file specifications until the device 
specification, "RKO". And again, the default extension for RKO:FILTIM is 

"MAC”. 


Warning: Due to the method used by PIP for copy operations, file creation times 
HFe not preserved during copy operations, although the date is handled 
correctly. When copying a file with PIP, the destination file will acquire the 
time the copy is made as its creation time. The EMT to set file times, 
described in Chapter 7, may be used to set the correct time in the new file. 
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Appendix D — RT-11 & TSX-Plus EMT CODES 


D,1 TSX-Plus RT-11 Compatible EMTs 

EMT Code Chan Name Description 


340 - 


.TTINR 

341 


.TTY0UT 

342 


.DSTATUS 

343 - 


• FETCH/.RELEAS 

344 


.CSIGEN 

345 


.CSISPC/.GTLIN 

346 0 


.LOCK 

347 0 


.UNLOCK 

350 


.EXIT 

351 


.PRINT 

352 - 


.SRESET 

353 0 


.QSET 

354 - 


.SETTOP 

355 


.RCTRL0 

357 - 


.HRESET 

374 

0 

.WAIT 

374 

1 

. SPND 

374 

2 

• RSUM 

374 

3 

.PURGE 

374 

4 

.SERR 

374 

5 

.HERR 

374 

6 

.CLOSE 

374 0 

7 

.TL0CK 

374 

10 

.CHAIN 

374 * 

11 

.MWAIT 

374 

12 

.DATE 

374 - 

13 

.ABTIO 

375 

0 

.DELETE 

375 

1 

.LOOKUP 

375 

2 

.ENTER 

375 

3 

.TRPSET 

375 

4 

.RENAME 

375 

5 

.SAVESTATUS 

375 

6 

.REOPEN 

375 

7 

.CLOSE 

375 

10 

•READ[C]tW] 

375 

11 

.WRIT[C][E][W] 

375 

12 

.WAIT 

375 * 

13 

•CHC0PY 

375 

14 

.DEVICE 

375 - 

15 

.CDFN 

375 - 

20 

.GTJB 


Get character from terminal 

Send character to terminal 

Get device information 

Load/Unload device handlers 

Call command string interpreter 

Get command line 

Lock USR in memory 

Allow USR to swap 

Return to monitor 

Display string at terminal 

Software reset 

Increase I/O queue size 

Set program upper limit 

Reset CTRL-0 

Stop I/O then .SRESET 

Wait for I/O completion 

Suspend mainline program 

Resume mainline program 

Free a channel 

Inhibit abort on error 

Enable abort on error 

Close channel 

Try to lock USR 

Pass control to another program 

Wait for message 

Get current date 

Abort I/O in progress 

Delete a file 

Open existing file 

Create file 

Intercept traps to 4 and 10 
Rename a file 
Save channel information 
Restore channel information 
Close channel 

Read from channel to memory 
Write from memory to channel 
Wait for I/O completion 
Open channel to file in use 
Load device registers on exit 
Define extra I/O channels 
Get job information 
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EMT 

EMT 

Codes 

Code i 

"han Name 

Description 

375 


21 

.GTIM 

Get time of day 

375 


22 

.MRKT 

Schedule completion routine 

375 


23 

. CMKT 

Cancel mark time 

375 


24 

.TWAIT 

Timed wait 

375 

* 

25 

.SDAT[C][W] 

Send data to another job 

375 

* 

26 

.RCVD[C][W] 

Receive data from another job 

375 


27 

.CSTAT 

Return channel information 

375 


30 

. SFPA 

Trap floating point errors 

375 

0 

31 

0 .PROTECT 

Control interrupt vector 

375 

0 

31 

1 .UNPROTECT 

Release interrupt vector 

375 


32 

.SPFUN 

Special device functions 

375 

* 

33 

•CNTXSW 

Context switch 

375 


34 

0 .GVAL 

Get monitor offset value 

375 

_ 

34 

1 .PEEK 

Get low memory value 

375 


34 

2 .PVAL 

Change monitor offset value 

375 

— 

34 

3 .POKE 

Change low memory value 

375 


35 

. SCCA 

Inhibit CTRL-C abort 

375 


36 

0 .CRRG 

Create an extended memory region 

375 


36 

1 .ELRG 

Eliminate an extended memory region 

375 


36 

2 .CRAW 

Create a virtual address window 

375 


36 

3 .ELAW 

Eliminate a virtual address window 

375 


36 

4 .MAP 

Map virtual window to XM region 

375 


36 

5 .UNMAP 

Get window mapping status 

375 


36 

6 .GMCX 

Obtain window status 

375 

* 

37 

0 .MTSET 

Set terminal status 

375 

* 

37 

1 .MTGET 

Get terminal status 

375 

* 

37 

2 .MTIN 

Get character from terminal 

375 

* 

37 

3 .MTOUT 

Send character to terminal 

375 

* 

37 

4 .MTRCTO 

Reset CTRL-0 

375 

* 

37 

5 .MTATCH 

Lock terminal to job 

375 

* 

37 

6 .MTDTCH 

Release terminal from job 

375 

* 

37 

7 .MTPRNT 

Display string at terminal 

375 

* 

37 

10 .MTSTAT 

Get system status 

375 


40 

.SDTTM 

Set date and time 

375 


41 

.SPCPS 

Change mainline control flow 

375 


42 

.SFDAT 

Change file date 

375 

Notes 

43 

.FPROT 

Change file protection 


* Not supported, will cause error. 

0 Treated as NOP. 

- Minor differences, see Chapter 14. 
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D.2 TSX-Plus Specific EMTs 


EMT 

Code 

Chan 

Name 

Description 

375 

101 


UNLALL 

Unlock all blocks 

375 

102 


LOCKW 

Wait for locked block 

375 

103 


TLOCK 

Try to lock a block 

375 

104 


SNDMSG 

Send message on named channel 

375 

105 


GETMSG 

Get message from named channel 

375 

106 


WATMSG 

Wait for message on named channel 

375 

107 

0 

SPLFRE 

Get number of free spool blocks 

375 

110 

0 

TSXLN 

Get line number 

375 

111 

0/1 

ACTODT 

Reset/set 0DT activation mode 

375 

113 


UNLOCK 

Unlock a block 

375 

114 

0 

TTOBLK 

Send block of text to terminal 

375 

115 

0 

TTIBLK 

Get block of test from terminal 

375 

116 

0 

CKTTIE 

Check for terminal input errors 

375 

117 

0 

SETTTO 

Set terminal read time-out 

375 

120 

0/1 

HIEFF 

Reset/set high-efficiency mode 

375 

121 


CKWSHR 

Check for writes to shared file 

375 

122 


SAVSHR 

Save shared file information 

375 

123 

0 

CKACT 

Check for activation characters 

375 

125 


SHRFIL 

Declare file for shared access 

375 

127 

0 

SEND 

Send message to another line 

375 

132 

0 

STRTDJ 

Start a detached job 

375 

132 

1 

STATDJ 

Check detached job status 

375 

132 

2 

ABRTDJ 

Abort a detached job 

375 

133 

0 

DCLBRK 

Establish break sentinel control 

375 

134 

0 

MOUNT 

Mount a directory structure 

375 

135 

0 

DISMNT 

Dismount a directory structure 

375 

136 

0 

INITPA 

Initiate performance analysis 

375 

136 

1 

STRTPA 

Start monitoring performance 

375 

136 

2 

STOPPA 

Stop monitoring performance 

375 

136 

3 

HALTPA 

Terminate performance analysis 

375 

137 

0 

TTYPE 

Get terminal type 

375 

140 

0 

PHYADD 

Convert virtual to physical address 

375 

140 

1 

PEEKIO 

Peek into the 1/0 page 

375 

140 

2 

POKEIO 

Poke into the 1/0 page 

375 

140 

3 

BISIO 

Bit-set into the I/O page 

375 

140 

4 

BICIO 

Bit-clear into the I/O page 

375 

140 

5 

MAPIOP 

Map PAR7 to the 1/0 page 

375 

140 

6 

MAPMON 

Map PAR7 to simulated RMON 

375 

140 

7 

LOKLOW 

Lock job into lowest memory 

375 

140 

10 

UNLOKJ 

Unlock job from memory 

375 

140 

11 

ATTVEC 

Attach to interrupt vector 

375 

140 

12 

RELVEC 

Release interrupt vector 

375 

140 

13 

LOKJOB 

Lock job without re-positioning 

375 

140 

14 

STEALS 

Get exclusive system access 
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EMT Code Chan Name Description 


375 

140 

15 

RTURNS 

Relinquish exclusive system access 

375 

140 

16 

SETPRI 

Set user mode priority level 

375 

140 

17 

MAPPHY 

Map to physical memory 

375 

140 

20 

ATTSVC 

Attach interrupt service routine 

375 

140 

21 

SCHCMP 

Schedule completion routine 

375 

141 

0 

MEMTOP 

Control size of job 

375 

143 

0 

USERTS 

Associate with run-time system 

375 

143 

1 

MAPRTS 

Map run-time system into job 

375 

144 

0 

JSTAT 

Get job status information 

375 

145 


FILINF 

Get file directory information 

375 

146 


SFTIM 

Set file creation time 

375 

147 

0/1 

GSUNAM 

Get/set user name 

375 

150 

0 

SETPRI 

Set job execution priority 

375 

151 


SPHOLD 

Set spooler HOLD/NOHOLD 

375 

152 

0 

SELOPT 

Select terminal option 

375 

153 

0 

NONINT 

Set [non]interactive job status 
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Appendix E ~ SUBROUTINES USED IN EXAMPLE PROGRAMS 


E. 1 PRTOCT - Print an octal value 

The following subroutine accepts a value in RO and prints the 6 digit octal 
representation of that value at the terminal. 



.TITLE 

PRTOCT 



•ENABLE 

LC 


; Print 

octal value of the word 

in RO 


•MCALL 

.PRINT 



.GLOBL 

PRTOCT 


PRTOCT: 

MOV 

R1,-(SP) 

;Save R1-R3 on the stack 


MOV 

R2,-(SP) 



MOV 

R3,-(SP) 



MOV 

//E0W.R2 

;Point to end of 6 char output buffer 


MOV 

# 6,R3 

;Set up counter for 6 chars 

1$: 

MOV 

R0,R1 

;Set up mask for low 3 bits (Is digit 


BIC 

#177770,R1 

;Get low 3 bits 


ADD 

#'0,R1 

;Convert to ASCII 


MOVB 

R1,-(R2) 

;Fill octal digits in from end 


CLC 




ROR 

RO 



ASH 

//—2, RO 

;Shift out bits just converted 


SOB 

R3,l$ 

;Repeat for 6 chars 


.PRINT 

#CHARS 

;Display result at console 


MOV 

(SP)+,R3 

;Restore registers R1-R3 


MOV 

(SP)+,R2 



MOV 

(SP )+, Rl 



RETURN 



CHARS: 

.BLKB 

6 

;6 char output buffer 

EOW: 

.ASCII 

<200> 

;No CR terminator for .PRINT 


• EVEN 




.END 




E.2 PRTDEC - Print £ decimal value 

The following subroutine accepts a value in RO and prints the decimal represen¬ 
tation of that value at the terminal with no leading zeroes. 


.TITLE PRTDEC 
.ENABL LC 


Print the decimal value of the word in RO 


.MCALL 

.PRINT 

.GLOBL 

PRTDEC 

PRTDEC: MOV 

R1,-(SP) 


;Save R1 and R2 


- 237 - 



















# 






Subroutines for Examples 



MOV 

R2,-(SP) 

;Point to end of output buffer 


MOV 

#BUFEND,R2 


MOV 

RO.Rl 

;Set up for DIV 

1$: 

CLR 

RO 

;Clear high word for DIV 

DIV 

#10.,R0 

;Get least significant digit 


ADD 

#'0,R1 

;Make remainder into ASCII 


MOVB 

R1,-(R2) 

;Save digit in output buffer 


MOV 

R0,R1 

;Set up for next DIV 


BNE 

1$ 

;Until nothing left 


.PRINT 

R2 

;Display number at the terminal 


MOV 

MOV 

RETURN 

(SP)+,R2 

(SP)+,R1 

;Restore Rl and R2 


• BLKB 

5 

;5 char output buffer 

BUFEND: 

.BYTE 

.EVEN 

.END 

200 

;No CR terminator for .PRINT 


E.3 PRTDE2 


Print a 2 digit decimal value 


The following subroutine accepts a value in RO and prints the decimal represen¬ 
tation of it at the terminal. The value must be in the range of 0 to 99. 


.TITLE PRTDE2 
.ENABLE LC 


; Print a 2-digit decimal value from RO 


•MCALL .PRINT 
.GLOBL PRTDE2 


PRTDE2: MOV 
MOV 
MOV 
MOV 
MOV 
MOVB 
MOV 

2$: CLR 

DIV 
ADD 
MOVB 
MOV 
SOB 

.PRINT 

MOV 

MOV 

MOV 

RETURN 


R1,-(SP) 

R2,-(SP) 

R3,-(SP) 

R0,R1 

#<BUFFER+2>,R2 
#200,(R2) 

#2,R3 

RO 

#10.,RO 

#'0,R1 

R1,-(R2) 

R0,R1 

R3,2$ 

#BUFFER 

(SP)+,R3 

(SP)+,R2 

(SP)+,R1 


;Get copy of char in Rl 
;Point to buffer. 

;Set end for .PRINT 

;Clear high word for DIV 
;Get low digit 
;Convert low digit to ASCII 
;Put digit in char buffer 
;Roll quotient for next DIV 
;Two digits only 
;Display the result 
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Subroutines for Examples 


BUFFER: .BLKB 
.EVEN 
.END 


E.4 PRTR50 - Print a RAD50 word at the terminal 

The following subroutine accepts a one word RAD50 value in RO and prints its 
ASCII representation at the terminal. 

Example: 


.TITLE 

PRTR50 

.ENABL 

LC 

y 

; Display the RAD50 value 

.MCALL 

.TTYOUT 

•GLOBL 

PRTR50 

PRTR50: MOV 

R1,-(SP) 

MOV 

R4,-(SP) 

MOV 

R5,-(SP) 

MOV 

R0,R5 

CLR 

R4 

DIV 

#50,R4 

MOV 

R5,R1 

MOV 

R4,R5 

CLR 

R4 

DIV 

#50,R4 

.TTYOUT 

R50TBL(R4) 

.TTYOUT R50TBL(R5) 

.TTYOUT 

R50TBL(R1) 

MOV 

(SP)+,R5 

MOV 

(SP)+,R4 

MOV 

RETURN 

(SP)+,R1 

.NLIST 

BEX 

R50TBL: .ASCII 
.EVEN 
.END 

/ ABCDEFGH 


;Need place to store last char 
;Need R4 and R5 for DIV 

;Get copy of rO into dividend 
;Zero high word for DIV 
;Extract last char 
;Save last char (remainder) 
;Move quotient for next DIV 
;Zero high word for second DIV 
;Get first and second chars 
;Display first char (quotient) 
; and second char (remainder) 

; and last char 
;Restore registers 


0123456789/ 


E.5 DSPDAT - Print a date value at the terminal 

The following subroutine accepts a date value in RO and prints the date 
representation at the terminal. 
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Subroutines for Examples 


.TITLE DSPDAT 
.ENABL LC 

; Print a date value from RO 

.MCALL .PRINT 
.GLOBL DSPDAT,PRTDEC 

MONMSK = 036000 
DAYMSK = 001740 
YRMSK = 000037 


DSPDAT: MOV 
MOV 
BIC 
ASH 
CALL 
MOV 
BIC 
ASH 
ADD 
•PRINT 
MOV 
BIC 
ADD 
CALL 
MOV 
RETURN 


R1,-(SP) 

R0,R1 

iTCDAYMSK.RO 

#-5,R0 

PRTDEC 

R1,R0 

#~CMONMSK,RO 
#-7,R0 
#MONTBL,RO 
RO 

Rl ,R0 

#~CYRMSK,RO 
#72.,R0 
PRTDEC 
(SP)+,R1 


;Get copy of date in Rl 
;Mask in only day bits (5-9) 

;Shift down 
;Print it out 
;Get fresh copy of date 
;Use only month bits (10-13) 

;Shift down to index into month table 

;Point into table 

;Display the month 

;Fresh copy again 

;Use only year bits 

;Year since 1972 

;Display the year 


MONTBL: 


•NLIST BEX 

.ASCII /-NON-/<2O0X0><0> 
.ASCII /-Jan-/<200><0X0> 
.ASCII /-Feb-/<200X0><0> 
.ASCII /-Mar-/<200><0X0> 
.ASCII /-Apr-/<200X0X0> 
.ASCII /-May-/<200><0X0> 
•ASCII /-Jun-/<200><0><0> 
.ASCII /-Jul-/<200X0X0> 
•ASCII /-Aug-/<200><0><0> 
.ASCII /-Sep-/<200X0X0> 
.ASCII /-Oct-/<2 00X0X0> 
.ASCII /-Nov-/<200><0X0> 
.ASCII /-Dec-/<200><0><0> 
.EVEN 
.END 


- 240 - 







Subroutines for Examples 


E.6 DSPTI3 - Display a 3-second format time value 

The following subroutine accepts a special 3-second time value in RO and prints 
the time value at the termina 1 . 

•TITLE DSPTI3 
•ENABL LC 

; Display special 3-sec format time value from RO 


.MCALL 

.TTYOUT 


.GLOBL 

DSPTI3.PRTDE2 


DSPTI3: MOV 

R1,-(SP) 


MOV 

RO ,R1 

;Set up for divide 

CLR 

RO 


DIV 

#20.,R0 

;Get # of 3-SEC'S since midnight 

MOV 

R1,-(SP) 

;Put on stack 

ASL 

Rl 

;2X 3-SEC'S 

ADD 

R1,(SP) 

;Plus IX gives 3X = seconds 

MOV 

RO, Rl 

;Get rest of time 

CLR 

RO 

;Set up for next divide 

DIV 

#60.,RO 

;Get number of minutes 

MOV 

R1,-(SP) 

;And save on stack 

CALL 

PRTDE2 

;What's left is hours, display 

.TTYOUT 

#': 


MOV 

(SP)+,R0 

;Recover minutes 

CALL 

PRTDE2 

;Display minutes 

.TTYOUT 

#': 


MOV 

(SP)+,R0 

;Recover seconds 

CALL 

PRTDE2 


MOV 

(SP)+,R1 


RETURN 



.END 




E.7 ACRTI3 - Convert a time value to special 3-second format 

The following subroutine accepts a time value from the terminal and converts it 
to a special 3-second internal format. The value is returned in RO. 

.TITLE ACRTI3 
.ENABL LC 

; Accept a time from the keyboard and return it in 
; a special 3—second format in RO 

.GLOBL ACRTI3 

ACRTI3: MOV Rl,-(SP) 
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broutines for Examples 


1 $: 


2 $: 

3$: 


1 $: 


2 $: 


MOV 

R2,-(SP) 

MOV 

R3,-(SP) 

CLR 

HOURS 

CLR 

MINITS 

CALL 

GETNUM 

BCS 

2$ 

MUL 

#<60.*20.>,R3 

MOV 

R3,HOURS 

TST 

NUMERR 

BNE 

1$ 

CALL 

GETNUM 

BCS 

2$ 

MUL 

#20.,R3 

MOV 

R3, MIN ITS 

TST 

NUMERR 

BNE 

1$ 

CALL 

GETNUM 

BCS 

2$ 

CLR 

R2 

DIV 

#3,R2 

ADD 

MINITS,R2 

ADD 

HOURS,R2 

MOV 

R2,R0 

CLC 


BR 

3$ 

SEC 


MOV 

(SP)+,R3 

MOV 

(SP)+,R2 

MOV 

(SP)+,R1 

RETURN 


: CLR 

NUMERR 

CLR 

R3 

MOVB 

(R0)+,R1 

CMPB 

Rl,#'0 

BLT 

2$ 

CMPB 

Rl,#'9 

BGT 

2$ 

MUL 

#10.,R3 

SUB 

r o,ri 

ADD 

Rl ,R3 

BR 

1$ 

CMPB 

Rl,#': 

BEQ 

3$ 

INC 

NUMERR 

TSTB 

Rl 

BEQ 

3$ 

SEC 



3$: 


RETURN 

CLC 

RETURN 


;Make sure it's reentrant 

;Accrue decimal hours 
;Return with error 
;Convert hours to 3-sec periods 
;Save hours in 3-sec units 
;Did we hit end of input? 

;Yes, return value 
;Accrue decimal minutes 
;Return with error 
;Convert minutes to 3—sec periods 
;Save minutes in 3-sec units 
;End of input? 

;Yes, return value 
;Accrue decimal seconds 
;Return with error 

;Convert seconds into 3—sec periods 

;Quotient stays in R2 

;Add in 3-secs from minutes 

;Add in 3-secs from hours 

;Return it in RC 

;Say no error 

;Return 

;Say there was an error 


;Say no error yet 
;Initialize number 
;Get next digit into R1 
;Less than "0? 

;Not a digit 
;Greater than '9? 

;Not a digit 

;Shift previous digits 

;Convert current digit to binary 

;And include in number 

;Get digits til next separator 

;Is it a legal separator? 

;Yes, return 
;Say it may be end 

;Was it a nul (end of input string). 

;Yes, return 

;No, say invalid input 

;Error return 

;No error 
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HOURS: 

MINUS: 

NUMERR: 


.WORD 0 
.WORD 0 
.WORD 0 
.END 
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Appendix F — TSX~Plus USER ERROR MESSAGES 


Several different categories of errors can generate messages, ranging from 
errors which are fatal to the operating system to something as simple as an 
incorrect file specification. Errors are identified by the name of the program 
which recognized the error and one or more lines of descriptive information. 
Errors identified by utility programs are identified by the name of the utility 
(e.g. , 7PIP-F, ?DUP-F, 7KED-F) and may or may not abort the program. For more 
information about utility program error messages, consult the appropriate RT-11 
manual (RT-11 System Message Manual, RT-11 System Utilities Manual, RT-11 
Keypad Editor User's Guide, etc.). Errors which are fatal to the TSX-Plus 
operating system (identified as 7TSX-F) report error conditions for which 
time-sharing users are not usually responsible and usually cannot correct. TSX 
fatal errors should be reported to the system manager who should consult the 
TSX-Plus System Manager's Guide for more information. Errors which are not 
fatal to the operating system but which indicate a user mode error are reported 
as monitor errors. This Appendix describes TSX-Plus specific monitor error 
messages. 

All user mode fatal monitor error messages have the syntax: 

7KM0N-F-" message 


or 


7M0N-F-” message " 

where the "7KM0N-F” form is used if the error occurs while using the keyboard 
monitor and the "7M0N-F” form is used for errors which occur within a user 
progr am - in some cases, the message is only informational rather than 
indicating an error. In these cases, the message is of the form: 

7KM0N-I-" message " 

Error messages are consistent with RT—11 usage insofar as possible. Monitor 
error messages unique to TSX-Plus are described below. Consult the RT-11 
System Message Manual for monitor errors not described here. 

Ambiguous o ption 

Not enough characters were specified to distinguish between options. 

ASSIGN table full 

Maximum number of logical assignments (15 per user) exceeded. SHOW 
ASSIGNS and DEASSIGN unnecessary logical assignments. 

Attempt to increase^ MAXPRIORITY above current value 

Maximum job priority may be restricted by the system manager. It may be 
reduced, but it may not be increased during a time-sharing session. 

Cannot find SY:TSODT.REL file . , 

-The - relocatable copy of the TSX-Plus ODT debugging program was not found 

on the system device. Copy the file "TSODT.REL" from the distribution 

medium to SY. 
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Error Messages 


Cannot file SY:TSXUCL.SAV 

A command was attempted to be interpreted as a user-defined command, but 
the TSXUCL program could not be found. Copy TSXUCL.SAV from the distrib¬ 
ution to SY. 

Cannot open alignment file 

The alignment file specified in a SPOOL align command cannot be opened. 
Cannot open logoff com mand file 

A logoff command file which was specified during job start-up could not be 
found while logging the job off. 

Cannot open spool device 

The spooler cannot access the spool device. Verify the device name used 
in the SPOOL macro during TSX-Plus generation and check for correct device 
assignments. 

Can^t open system accou nting file 

The file SY:ACCESS.TSX cannot be found during logon or logoff. This file 
is created by the system manager. 

Closing log file 

If a device on which a terminal output log file is open is initialized or 
squeezed, the log file is first closed. 

Command file nesting too deep 

Maximum depth of command file nesting exceeded. The depth of command file 
nesting allowed depends on the number and length of parameter strings. 
Three levels are possible even with long strings and as many as seven 
levels are possible with no parameters. See Chapter 3 for more infor¬ 
mation on command files. 

Command file not found 

The specified command file was not found. See Chapter 2 for an explan¬ 
ation of command interpretation including default devices, and Chapter 3 
for more information on command files. 

Command file p arameter string too long 

Total number of characters in parameter string exceeds the maximum allowed 
length of 60 characters. See Chapter 3. 

Command string too complicated 

The command string expansion is too large for the internal CCL buffer. 
Reduce the complexity of the command string. The SET CCL TEST command may 
be used to examine the expanded command string generated by high level 
commands. 
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Error Messages 


Device is mounted by another user 

The INITIALIZE and SQUEEZE commands are invalid if the device is MOUNTed 
by any other user. This minimizes the opportunity for data corruption 
when other users may be writing to a device. See the INITIALIZE and 
SQUEEZE commands for motivation. 

Device is still mounted by other users 

This informational message is displayed when a DISMOUNT request is issued 
for a device which is also MOUNTed by other users. See the INITIALIZE and 
SQUEEZE commands for motivation. 

Device or file is access restricted 

User does not have access privilege to requested device or file. The 
system manager may restrict user access to individual devices and files. 

Directory I/O error 

A device directory failed internal consistency checks. Devices must have 
valid RT-11 format directories for use with TSX-Plus. This error may also 
occur when attempting to use 22-bit addressing with DMA devices when the 
handler or hardware does not support 22-bit addressing. 

Handler active — Can^t update running copy 

An attempt was made to perform a SET command on a device handler which was 
in use. If the handler is idle when the SET is issued, the change will be 
made, otherwise, the running copy of the handler is not altered. Reissue 
the command when the handler is not active. 

Illegal use of wildcards 

Wildcards may not be specified for (part of) this command. 

IND already active 

The IND program cannot be run from within a command file which is being 
executed under control of the IND program. 

IND is not available 

The IND.SAV program was not on the system disk during TSX-Plus start-up. 
IND is provided with RT-11 version 5 and later. 

Invalid logical disk name 

Logical subset disks must be mounted as LDO through LD7. 

Invalid multiple value on option 

More than one parameter was specified for an option which only accepts 
one. 
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Error Messages 


Invalid or uninitialized directory 

A~disk device must contain a valid RT-11 format directory to be accessed 
by any operation other than INITIALIZE. Logical subset disks must be 
initialized before first use. This error may also occur when attempting 
to use 22-bit addressing with a DMA device and either the device handler 
or hardware does not support 22-bit addressing. 

Invalid SAV file 

A file specified with an R or RUN command failed internal consistency 
checks. The file may be damaged. An incorrect file type may have been 
specified - the default type is "SAV". 

Invalid address as EMT argument _ 

Sn address specified in a monitor call was odd or was not within the job s 
address space. The value returned as the abort location is the address of 
the instruction or the EMT that caused the error. 


Invalid file name 

An invalid file name was specified. Check for typing errors, names too 
long, and correct file specification format. 

Invalid line number 

An invalid line number was specified for a KILL or DETACH command. 

Invalid start addr ess for program 

The start address for the program was outside of the program s memory 
bounds or on an odd address. A MACRO program may have an incorrect 
starting address specified with the .END directive. The file may be 
damaged. An incorrect file type may have been specified - the default is 
"SAV”. 

Kernel mode trap within TSX-P lus 

A lcerneT~mode trap error usually indicates the operating system image has 
been corrupted due to hardware or software failure. Record the full error 
message and report the error to the system manager. This error can also 
be generated by attempting to access a non-existent memory address with 
the real-time EMT's to access the I/O page. 

Line is gagged 

Messages cannot be sent to lines which have SET TT GAG unless those lines 
are waiting in TSKMON for a command. 

Line too long ... 

The expanded CCL command was too long. Commands are expanded into the 

chain data area, locations 500 - 777. See the SET CCL TEST command. 
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Error Messages 


Log file overflow 

An error was reported while writing to the terminal output log file. This 
is most commonly an attempt to write past end-of-file. Make more room on 
the output device, specify a file size with the SET LOG command, or use 
the SET LOG NOWRITE option to reduce the volume of log file output. 

Logical Disk support was not generated into system 

Attempts to MOUNT a logical subset disk are not valid unless support for 
logical subset disks was selected when generating TSX-Plus. 

Logical disks must be nested in order of increasing unit 

When a file residing within a logical subset disk is to be mounted as 
another logical subset disk, it must be assigned a higher number than the 
outer level logical subset disk. For example, the following command is 
invalid: MOUNT LD1 LD3:MYDISK; whereas the following is acceptable: 

MOUNT LD3 LDl:MYDISK. 

Max allowed number of devices already mounted 

The number of device directories which may be cached is defined during 
system generation. DISMOUNT devices on which caching is no longer needed 
or consult the system manager. 

Memory size change not allowed in non-swapping TSX system 

Jobs may not change size dynamically unless job-swapping was enabled 
during system generation. Consult the system manager. 

Missing equal sign 

The equal sign was missing on a SET device command. 

No defined operator's console 

No operator console was defined during system generation. Form mount 
requests and messages using the OPERATOR command are sent to the operator 
console. 

No free detached job lines 

The maximum number of detached job lines is specified during system 
generation. Either wait for a job to terminate, stop one by use of the 
DETACH/KILL command, or ask the system manager to increase the number of 
detached lines. 

Not enough memory to run program 

A file was too large (or the size specified in the SAV image was too 
large) to fit in the space allocated to the job. See Appendix A for more 
information on program size specifications. Use overlay segments or chain 
requests to reduce the program size. Use the MEMORY command to request 
more memory for your job. Note that you cannot use the MEMORY command in 
a non-swapping environment; see the system manager. 
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Error Messages 


Performance monitor is in use by user number nn 

The performance monitor facility is already in use. Only one job may use 
it at a time. 

Priority value must be in the range ... 

Job priority may not be set less than 0, nor higher than the maximum 
allowed priority. 

Prompt string too long 

Prompt strings may not be longer than 8 characters. 

Save file I/O error 

An i/o error occurred while reading the SAV file. Check that the disk is 

still on line. It is also possible that the SAV file or the directory is 

damaged. 

SL was not included at system generation 

The SET SL ON command may not be issued unless support for the single line 
editor was selected when generating TSX-Plus. 

System was not generated _to support performance monitoring 

Performance monitoring is an optional feature that must be included during 
system generation. See the system manager. 

Terminal type must be set to VT100 or VT52 

The SET SL ON command may only be issued if the current terminal type is 

VT100 or VT52. Other terminal types are not supported by the single line 

editor. 

Table ove rflow 

Too many devices/files have been specified in the ACCESS command. See the 
system manager. 

This command only legal in startup co mmand file 

The ACCESS a"nd SET LOGOFF commands are only valid in startup command 
files. 

This operation not legal with SY (system) device 

The device which was booted when starting TSX-Plus may not be initialized 
or squeezed while running TSX-Plus. If it is necessary to initialize or 
squeeze this device, do so while running RT-11. 

Too many completion routines 

You have attempted to connect too many completion routines to interrupt 
vectors. The number of interrupt vectors that can be connected to 
completion routines is determined during system generation. See the 
system manager. 
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Error Messages 


Too many files 

The command interpreter uses standard command string format: up to 6 
input files and 3 output files. Reduce the number of file specifications 
accordingly. 

Too many parameters to command file 

TSX-Plus command files accept a maximum of six parameters. See Chapter 3. 
Trap to 14 

Abort location == nnnnnn 

Invalid breakpoint trap executed, 
address of the instruction following 

Trap to 20 

Abort location == nnnnnn 

Invalid I0T instruction executed, 
address of the instruction following 

Trap to 34 

Abort location = nnnnnn 

Invalid TRAP instruction executed, 
address of the instruction following 

TSGEN was modified without relinking TSKMON 

Whenever a new TSX-Plus system generation is done, both TSX and TSKMON 
must be relinked. See the system manager. 

Unable to allocate memory for virtual overlays 

The system failed to successfully allocate extended memory regions when 
trying to run a program with virtual overlays. Unlock jobs from memory or 
increase the PLAS region swap file size. 

Unable to open log file 

The system reported an error when attempting to create a file for terminal 
output logging. Check the file specification, verify that there is room 
and that the output device is not write protected. 

User command interface program not available 

The system could not locate the file specified with the command: 
SET KMON UC1[=filnam]. Check the file specification. The default file is 
SY:UKMON.SAV. 

USR called from completion routine 

You cannot call system service routines that use TSUSR from a completion 
routine. This includes: .LOOKUP, .ENTER, .RENAME, .DELETE, .CLOSE, 

.DSTATUS, .SFDAT, and •FPROT. 


The abort location provided is the 
the trap. 


The abort location provided is the 
the trap. 


The abort location provided is the 
the trap. 
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Error Messages 


USR err #n 

All of the following USR errors result from consistency checks performed 
in closing a tentative file (creating a permanent file). These are 
usually indicative of a strange hardware condition, such as exchanging or 
squeezing a disk while a file is open. 

USR err # 1 

TSUSR can't find tentative file entry for specified file on close. 

USR err # 2 

File length in channel block is not equal to length in file entry. 

USR err # _3 

Highest block number written is greater than file length. 

USR err £ 4_ 

Empty file entry doesn't follow tentative file entry. 

USR err # 5 

Tentative file entry status was lost during close operation. This is 
usually an indication of hardware failure. 

Unrecognizable command 

TSX-Plus could not find a system command, a user-defined command, or a 
command file with that name. See Chapter 2 for more information on 
command interpretation. 

Value required for option 

A command was issued that required a value for an option, but no value was 
specified. Reissue the command correctly. 

You are not authorized to write to that device or file 

The system manager may restrict access to individual devices or files. 
See the system manager. 

You're not privileged for that command 

The command is a privileged command. The system manager may restrict the 
use of privileged commands. 

?CCL-W-This command may interfere with other users 

This warning is issued by CCL on INITIALIZE and SQUEEZE commands to warn 
you that other users using that device might be dismayed by what you are 
about to do. See the warning with the SQUEEZE command. 
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Appendix G — LOGICAL SUBSET DISKS 


Logical subset disks provide a method of logically partitioning a large disk 
into smaller units which can themselves be treated as directory structured 
devices. This is done by creating a (relatively large) file on a physical 
device and then creating a device directory and files within that file. The 
resulting pseudo device which is created within the file on the mother device 
is called a logical subset disk. Logical subset disks may also be nested. 
That is, one logical subset disk may be contained within another logical subset 
disk. This nesting may continue up to seven levels of logical subset disks 
within other logical subset disks. Logical subset disks may be initialized, 
squeezed, and have files created, opened, closed and deleted. They may also be 
assigned logical device names (e.g. OUT:, DK: , ABC:). Several keyboard 
commands are used to manipulate logical subset disks: DISMOUNT, MOUNT, SET LD 
and SHOW SUBSETS. 

Support for logical subset disks is built into the kernel of TSX-Plus. 
Therefore, it is not necessary to use the LD device handler and logical subset 
disks may be used under TSX-Plus with either version 4 or version 5 RT-11 
utilities. 

Logical subset disks are given the device names LDO through LD7. Each user may 
use all eight logical subset disks at any time. That is, if one user has 
mounted LDO then any other user may also use LDO simultaneously and they need 
not (and usually will not) refer to the same file containing the logical subset 
disk. If logical subset disks are nested, then the device numbers must 
increase with the level of nesting. For example, LDO may contain a file to be 
mounted as LDl. However, a file contained within LD1 may never be mounted as 
LDO. 

The typical sequence of operations when using logical subset disks is to: 1) 
create a file on a physical disk device; 2) mount that file as a logical subset 
disk; 3) initialize the new logical subset disk; 4) and then proceed to use it 
as any other disk device (except that it cannot be physically handled independ¬ 
ently of the surrounding real disk). Subsequent uses of the logical disk only 
require that the disk be re-mounted. The file need not be re-created, nor the 
logical subset disk re-initialized. 

The following example shows a typical sequence of commands which might be used 
to initiate use of a new logical subset disk. 

.CREATE DL1:MYDISK.DSK/ALLOCATE:500. 

.MOUNT LDO: DLl:MYDISK 

.INITIALIZE/NOQUERY LDO: 


. DISMOUNT LDO: 

In order to use this new logical disk at a later time, it would only be 
necessary to issue the MOUNT command: 

.MOUNT LDO: DLl:MYDISK DK: 
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The default (and recommended) file type for files intended to contain logical 
subset disks is .DSK. 

When logical subset disks are mounted, information about them can be obtained 
with the SHOW SUBSETS command. For example: 

.SHOW SUBSETS 

LDtT^-y DLlVMYDISK. DSK [500] 

To remove a logical subset disk from use, use the dismount command. For 
example: 

.ASSIGN DL1 DK 
. DISMOUNT LDO: 

Note that the disk files containing logical subset disks are automatically 
marked as protected files. In order to delete them, they must first be 
unprotected. 

It is possible with logical subset disks to create some unusual situations and 
conflicts. For example, it is possible to mount a logical subset disk and then 
unprotect and delete the file which contained it. This condition would be 
marked with an asterisk (*) with the SHOW SUBSETS command. In addition, the 
SET LD CLEAN command can be used to force the system to compare, verify and 
correct the information in its internal logical subset disk tables if possible. 
Obviously, the system will not go back and recreate deleted files. An implicit 
SET LD CLEAN is done each time the DUP utility is called (e.g. with the DELETE 
and SQUEEZE commands). 

For more information on the details of the commands used with logical subset 
disks, see the descriptions n.n Chapter 2 of the following commands: DISMOUNT, 
MOUNT, SET LD CLEAN and SHOW SUBSETS. 


-254- 















Appendix H — JOB EXECUTION PRIORITIES 


TSX-Plus jobs may be assigned execution priorities to control their scheduling 
relative to other jobs. The priority values range from 0 to 127. The maximum 
execution priority that may be assigned to a job can be controlled by the 
system manager by use of the TSAUTH account authorization program or the SET 
MAXPRIORITY command (see the TSX-Plus System Managers Guide). 

The priority assigned to a job is set by use of the SET PRIORITY keyboard 
command or the TSX-Plus EMT described in Chapter 7. The current priority for a 
job and the maximum authorized priority can be displayed by use of the SHOW 
PRIORITY keyboard command, and may be obtained from within programs with the 
.GVAL request. 

The priority values are arranged in three groups: the fixed-low-priority group 
consists of priority values from 0 up to the value specified by the PRILOW 
sysgen parameter; the fixed-high-priority group ranges from the value specified 
for the PRIHI sysgen parameter up to 127; the middle priority group ranges from 
(PRILOW+1) to (PRIHI-1). The following diagram illustrates the priority 
groups: 

+-+ 

127 —>| | 

I Fixed 
I high | 

I priorities I 

PRIHI —> j | 

H-+ 

I I 

Normal 

PRIDEF -->| job j 

I priorities I 

I I 

+-h 

PRILOW -->| I 

I Fixed 
I low 
I priorities I 

0 — > I I 

H-h 


Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other jobs. The job state does not influence the 
execution scheduling except as to whether the job is in a ready-to-run state or 
a wait state. A job with a fixed priority is allowed to execute as long as it 
wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 
fixed-low-priority group is intended for use by very low priority background 
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tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive; time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed-priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. For these jobs the job state is 
the primary factor in determining execution scheduling and the user-assigned 
job priority only influences the scheduling of jobs in the same state. See 
Chapter 5 of the TSX-Plus System Manager's Guide for further information about 
job scheduling. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority of 
normal jobs will never be reduced below the value of (PRILOW+1). 
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.ABTIO, 215 
. CDFN, 215 
.CHAIN, 215 
.CHCOPY, 215 
.CNTXSW, 215 
.CSIGEN EMT, 78 
•CSISPC EMT, 78 
.DEVICE, 215 
.DEVICE EMT, 185 
.FETCH, 215 
.FORK, 215 
.GTJB, 215 
.GTLIN EMT, 78 
.GVAL EMT 

Checking I/O page mapping, 170 
Special TSX-Plus use, 112 
.HRESET, 215 
.INTEN, 215 
.LOCK, 215 
.MTPS, 216 
.MWAIT, 216 
.PEEK, 172, 216 
.POKE, 172, 216 
.PROTECT, 202, 216 
.PURGE 

“Shared files and,~ 151 
.QSET, 216 
.RCVD, 216 
.RELEAS, 216 
.RSUM, 183 
. SAVESTATUS 

Shared files and, 151 
.SDAT, 216 
.SDTTM, 216 

.SETTOP, 111, 216, 219 
. SFPA, 216 
•SPND, 183 
.SRESET, 216 
.SYNCH, 217 
.TLOCK, 217 
.TTINR, 217 
.TTYIN EMT 

Command file input, 78 
Non-wait input, 59, 105 
Time-out value, 124 
.UNLOCK, 217 
.UNPROTECT, 217 
ABORT c oramand, 7 3 
Aborting jobs 

Detached jobs, 85 
Normal jobs, 36 


ACCESS command, 28 
ACRTI3, 241 

Activation characters, 97 
Checking for, 128 
Defining, 103 
Field width, 104 
ODT activation mode, 135 
Resetting, 104 
Time-out activation, 124 
Adapting RT-11 Real-time programs, 
202 

Administrative control, 3 
Alignment of forms, 96 
ASSIGN command, 28 
Assigns 

Displaying those in effect, 62 
B(ASE) command, 73 
Backing up in a spool file, 92 
BACKUP command, 29 
Basic operation, 9 
BATCH facility, 217 
Block locking 

See Shared files 
BOOT command, 29, 73 
Booting the system, 73 
Break sentinel control, 125 
BYE command, 29 
CACHE 

SHOW command, 63 
CACHE parameter 

Selecting appropriate size, 46 
Caching 
Data, 160 
Directories, 38 
Carriage-return 

Automatic line-feed, 106 
Cataloged procedures 
See Command files 
Chapter summaries, 4 
Character echoing, 57, 103 
CLOSE command, 73 
COBOL command, 29 
Command file control, 75 
Command files, 75 
Comments within, 77 
Control characters within, 78 
Controlling input, 78, 104 
Controlling listing, 58, 77, 78 
Displaying messages, 79 
Invoking, 17, 18, 76 
Nesting of, 77 
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Parameter strings, 76 
PAUSE command, 41 
Pausing execution, 79 
Setting error abort level, 48 
Command interpreter, 17 
Commands 

Defining, 20 

Listing user-defined, 63 
Common data areas, 203 
COMPILE command, 30 
Completion routine 

Connecting to an interrupt, 196 
Scheduling, 201 
Configuration 

SHOW command, 63 
Configuration requirements, 1 
Control characters, 11 
Ctrl-C, 11, 103 
Ctrl-0, 11 

Ctrl-Q, 11, 58, 59, 106 
Ctrl-R, 11 

Ctrl-S, 11, 58, 59, 106 
Ctrl-U, 11 
Ctrl-W, 11, 81 
Ctrl-Z, 11 

Within command files, 78 
Control files 

See Command files 
Cooperative file access 
See Shared files 
COPY command, 30 
C0RTIM 

SHOW command, 63 
C0RTIM parameter 
Setting value, 47 
CREATE command, 30 
CRT terminal support, 58 
D(EPOSIT) command, 73 
Data caching, 160 

Enabling use of, 148 
Setting number of cache buffers, 
53 

Suppression of, 160 
DATE command, 31 
DBL default compiler, 50 
DEASSIGN command, 31 
Debugging programs, 42 
Deferred character echoing, 57 


DELETE command, 31 
DELETE key 

Rubout filler character, 102 
DETACH command, 31, 83, 84, 85 
Detached jobs, 81, 82 
Aborting, 32, 85, 87 
Checking status, 32 
Checking status of, 84, 88 
Comparison with virtual lines, 
83 

Control EMTs for, 85 
Keyboard control commands, 31 
Starting, 31, 83, 85 
Device spooling 
See Spooling 
DIB0L command, 32, 73 
DIBOL default compiler, 50 
DIBOL record locking procedures, 
147 

DIBOL support subroutines, 223 
DIFFERENCES command, 32 
Directory caching, 38 

Dismounting a file structure, 
123 

Displaying mounted devices, 65 
Mounting a file structure, 122 
SQUEEZE command effect, 69 
DIRECTORY command, 32 
Directory information 
EMT to obtain, 136 
DISMOUNT command, 33, 253 
Dismounting a file structure, 123 
DISPLAY command, 34, 79 
DL-11, 1 
DSPDAT, 239 
DSPTI3, 241 
DUMP command, 34 
DZ-11, 1 

E(XAMINE) command, 73 
Echo control, 57, 103 
EDIT, 47 

EDIT command, 34 
Editor 

Selecting default, 47 
Single line, 12 
EMT codes 
table, 233 

EMT differences, 215 
EMT tracing, 47 
EMT's 

TSX-Plus specific, 107 


- 258 - 





# 






Index 


Error messages, 245 
Escape character 

Within command files, 78 
Escape sequence processing, 102 
Exclusive access to a file, 147 
Exclusive system control, 180 
releasing, 180 
EXECUTE command, 34 
Execution priority, 255 
Virtual lines, 81, 82 
Extended memory regions, 143 
Field width activation, 104 
Field width limit for TT input, 

106 

File 

Block locking, 147 
Data caching, 160 
Exclusive access, 147 
Opening for shared access, 147 
Protection modes, 147 
Shared access, 147 
File creation time, 138 
File directory information, 136 
Fixed-high-priority 
Determining, 112 
Fixed-low-priority 
Determining, 112 
Floating point, 216 
Foreground programs 
See Real-time support 
Form alignment procedure, 96 
FORM command, 34, 95 
Form feed control, 57 
Form names, 90, 95 
FORMAT program, 217 
FORTRAN c ommand, 3 5 
FRUN command, 73 
Generalized data cache 

Selecting appropriate size, 46 
GET command, 73 
Global data areas, 203 
GT 0N/0FF command, 73 
Hardware requirements, 1 
Hazeltine terminal support, 58 
HELP command, 35 

High-efficiency terminal mode, 42, 
100, 101, 104, 132 
HIPRCT 

SHOW command, 64 


HIPRCT parameter 
Setting value, 48 
I/O page 

Accessing, 145, 169 
IND 

Command file aborting, 48, 49 
Command file processing, 49 
Control of command files, 75 
INITIALIZE command, 35 
INSTALL command, 73 
Interactive jobs 

Selecting dynamically, 120 
Interprogram communication, 163 
Checking for messages, 165 
Common memory areas, 203 
Message channels, 163 
Sending a message, 163 
Waiting for a message, 166 
Interrupt completion routine, 196 
Interrupt processing 
(Diagram), 190 
Interrupts 

Connecting to real-time jobs, 

188 

INTI0C 

SHOW command, 65 
INTI0C parameter, 49 
Introduction, 1 
10 abort handling, 49 
Job number 

Determining, 112 
Job priority 

Determining, 112 
Maximum, 52 
Setting, 53, 117, 186 
SHOW command, 66 
Job scheduling, 2 
Job status information, 114 
Job status word 

Non-wait TT input, 59, 105 
Setting virtual flag with SETSIZ, 
221 

Virtual-image flag, 143 
K52, 47 

Virtual lines, 82 
KED, 47 

Virtual lines, 82 
Keyboard commands, 17, 28 
Abbreviation of, 17 
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Keyboard monitor 

Prompt character, 54 
KILL command, 36 
KJOB command, 36 
LA120 terminal support, 58 
LA36 terminal support, 58 
LD 

Handler, 217 
LD handler, 253 
Lead-in character, 99, 101 
Determining, 112 
LIBRARY c ommand, 3 6 
Line number 

Determining, 108 
Determining primary, 112 
Line-feed 

Echoing of, 106 

Ignored with tape mode, 59, 106 
LINK command, 36 
/XM switch, 143 
LOAD command, 73 

Locking a form on a spooled device 
90 

Locking a job in memory, 182 
Log off command files, 52 
Logging off, 10, 40 
Logging on, 9 
Password, 9 

Project programmer number, 9 
User name, 9 
Virtual lines, 81 
Logging terminal output, 51 
Logical device names, 28 
Assigning, 62 
Logical subset disks 
Dismounting, 33 
Mounting, 39 
Nesting, 253 
Using, 253 
Verifying, 51 

Lower-case character input, 58, 

103 

MACRO c ommand, 3 7 
MAKE command, 37 
Mapping virtual region, 178 
Maximum priority 
Determining, 112 
Setting, 52 


Memory 

Using as pseudo-disk, 145 
Memory allocation 
EMT to control, 111 
MEMORY command, 37 
Setting size in SAV file, 219 
MEMORY command, 37, 112, 219 
Memory mapping, 141 
Memory space 

Displaying value, 65 
Message channels, 163 
Message communication 

See Interprogram communication 
Messages 
error, 245 
Inhibiting, 57 

Sending to another line, 121 
Modification of shared files 
Checking for, 159 
MONITOR command, 38, 207 
MOUNT command, 38, 122, 253 
Mounting a file structure, 38, 122 
Multi-terminal EMTs, 215 
MUNG command, 40 
Non-interactive jobs 

Selecting dynamically, 120 
Non-wait TT input, 59, 105 
Normal programs, 143 
NUMDC parameter 
Setting value, 53 
SHOW command, 66 

Obtaining TSX-Plus system values, 
112 

ODT activation mode, 135 
ODT debugger, 217 
OFF command, 40, 82 
Opening, shared files, 147 
OPERATOR command, 40 
Operator communication, 40 
Operator privilege 
Determining, 112 
Real-time jobs, 169 
Optimization 
SET SIGNAL, 54 
Page length control, 58 
Paint character 

See Rubout filler character 
Paper tape mode 
See Tape mode 
PAR 7 mapping 

Determining, 112 
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Parameter strings for command files, 
76 

Password 

Changing, 9 
Logging on, 9 
PAUSE command, 41, 79 
Performance monitor, 207 
Control EMT's, 209 
Displaying results, 208 
MONITOR command, 38, 207 
Starting, 207, 209 
Physical address calculation, 184 
Physical address space, 141 
Physical memory access, 178 
PLAS support, 143 
Poke EMT, 174 
Primary line 

Determining, 112 
PRINT command, 41 
Printer form names, 90 
Priorities, 255 
Priority 

Maximum, 52 
PRIORITY 

S HOW c ommand, 6 6 
Priority level 
Setting, 53, 117 
setting, 186 
PRIORITY parameter 
Setting value, 53 
PRIVIR parameter, 118, 187, 256 
Program controlled terminal options 
See Terminal control 
Programmed Logical Address Space 
See PLAS support 
Programmer number 
Determining, 112 
Project number 
Determining, 112 
PROTECT cnmmatrd, 41 
Protected access to a file, 147 
PRTDE2, 238 
PRTDEC, 237 
PRT0CT, 237 
PRTR50, 239 

Pseudo-disk in memory, 145 
QUAN values 
Selecting, 54 
QUANxx parameters 
Setting value, 54 


SHOW command, 66 
QUEMAN, 217 
QUEUE, 217 
R command, 41 

/DEBUG switch, 42, 112 
/HIGH switch, 42 
/LOCK switch, 42 
/NONINTERACTIVE switch, 43 
/SINGLECHAR switch, 43, 105 
Implicit, 18 

Read time-out value for TT inputs, 
124 

Real-time completion routine, 196 
Real-time jobs 

Operator privilege, 169 
Real-time priority, 197 
Real-time support, 169 

Accessing the 1/0 page, 169, 172, 

177 

Adapting RT-11 programs, 202 
Device reset on exit, 185 
Interrupt connections, 188 
Locking a job in memory, 182 
Mapping to physical addresses, 

178 

Physical address calculation, 

184 

Poke EMT, 174 

Suspending/resuming execution, 

183 

Rebooting the system, 73 
Record locking, 147 
See Shared files 
REENTER command, 73 
Reentrant run-times 

See Shared run-time systems. 
Regions in extended memory, 143 
Releasing exclusive system control, 
180 

REMOVE command, 73 
RE NAME c ommand, 4 4 

Requesting exclusive system control, 
180 

RESET command, 44, 70, 73 
Resident run-times 

See Shared run-time systems. 
RES0RC, 217 
Restrictions 

Keyboard commands, 73 
Programs not supported, 217 
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RESUME command, 73 
RMON 

Real-time support consideration, 
170 

Simulated, 143 
SYSGEN options word, 107 
RT-11 

Returning control to, 72, 73 
Rubout filler character, 102 
RUN command, 44 

/DEBUG switch, 42, 112 
/HIGH switch, 42 
/LOCK switch, 42 
/NONINTERACTIVE switch, 43, 120 
/SINGLECHAR switch, 43, 105 
Run-time systems 

See Shared run-time systems. 
Running programs, 41, 44 
SAVE command, 73 

Scheduling a completion routine, 
201 

Scheduling of jobs, 2 
Scope type terminal support, 58 
SEND command, 44 
Sending messages, 121 
SET command, 45, 73 
CACHE, 46 
CCL, 46 
C0RTIM, 47 
EDIT, 47 
EMT, 47 
ERROR, 48 

Handler options, 45 
HIPRCT, 48 
IND, 49 
INTI0C, 49 
10, 49 

KM0N, 24, 49 
LANGUAGE, 50 
LD, 51, 253 
LOG, 51 
LOGOFF, 52 
MAXPRI0RITY, 52 
NUMDC, 53 
PRIORITY, 53 
PROMPT, 54 
QUANxx, 54 
SIGNAL, 54 
SL, 55 

TERMINAL, 56 


TT, 56 

TT ADM3A, 57 

TT DECWRITER, 57 

TT DEFER, 57 

TT DIABLO, 57 

TT ECHO, 57 

TT FORM, 57 

TT FORMO, 57 

TT GAG, 57 

TT HAZELTINE, 58 

TT LA120, 58 

TT LA36, 58 

TT LC, 58 

TT PAGE, 58 

TT QUIET, 58, 77 

TT QUME, 58 

TT SCOPE, 58 

TT SINGLE, 58 

TT TAB, 59 

TT TAPE, 59, 106 

TT terminal-type, 109 

TT VT100, 59 

TT VT50, 59 

TT VT52, 59 

TT WAIT, 59 

UCI, 24 

UCI=filnam, 24 
UCL, 21, 60 
UCL FIRST, 21, 60 
UCL LAST, 21, 60 
UCL MIDDLE, 21, 60 
UCL NONE, 21, 60 
VM, 61 

WILDCARDS, 61 

SET UCL command 
FIRST, 17 
LAST, 18 
MIDDLE, 17 
NONE, 19 

SETSIZ program, 112, 219 

Setting processor priority level, 
186 

Shared access to a file, 147 

Shared files, 147 

Checking for modification of, 
159 

Opening, 147 
Protection modes, 148 
Saving channel status, 151 
Testing for locked blocks, 156 
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Unlocking a block, 158 
Unlocking all locked blocks, 159 
Waiting for locked block, 154 

Shared run-time systems, 203 
Associating with job, 203 
Displaying run-times available, 
67 

Mapping into job region, 144, 

205 

SHOW command, 62 
ALL, 62 
ASSIGNS, 62 
CACHE, 63 
COMMANDS, 63 
CONFIGURATION, 63 
CORTIM, 63 
DEVICES, 64 
HIPRCT, 64 
INTIOC, 65 
JOBS, 65 
MEMORY, 65 
MOUNTS, 65 
NUMDC, 66 
PRIORITY, 66 
QUANxx, 66 
QUEUE, 67 
RUN-TIMES, 67 
SUBSETS, 67, 253 
TERMINALS, 68 
USE, 68 

SHUTDOWN command, 73 

Signaling 

System tuning parameters, 54 

Simulated RMON 

Access through page 7, 143 
Real-time support consideration, 
170 

Single character activation, 43, 
58, 97, 105 

Single line edi-ttrr, 12" 

SET options, 55 

Skipping forward in a spool file, 
91 

SL, 12 

Handler, 217 
SET command, 55 

Special Chain Exit, 24 

SPOOL command, 69, 90 
Aligning a form, 91 
Backing up in a spool file, 92 


Checking device status, 92 
Deleting queue entries, 91 
HOLD & NOHOLD options, 93 
SING & MULT options, 92 
Skipping forward in a file, 91 
Specifying a form name, 90 
Spooling, 89 

Aligning a form, 91 
Backing up in a file, 92 
Checking device status, 92 
Concept of, 89 
Deleting queue entries, 91 
Directing output to, 89 
Displaying requests in queue, 

67 

Form names, 95 
Holding output, 93 
Number of free spool blocks, 134 
Single and multifile processing, 
92 

Skipping forward in a file, 91 
Specifying a form name, 90 
Specifying default form name, 

34 

SPOOL command, 69 
Spooling, Operation of, 89 
SQUEEZE command, 69 
SRUN command, 73 
START command, 73 
Start-up command file, 9 
Starting detached jobs, 83 
STOP command, 72 
Stopping the system, 72, 73 
Summaries of chapters, 4 
SUSPEND command, 73 
SYSGEN options word, 107 
SYSTAT command, 70 
System configuration 
Showing, 63 
System device 

Determining, 112 
System resource management, 2 
System tuning 
SET SIGNAL, 54 
System values 
Obtaining, 112 
Tab character support, 59 
Tape mode, 59, 106 
TECO, 47 

MAKE command, 37 
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Use within command files, 78 
TECO command, 71 
Terminal control, 97 


Selecting, 54 
TYPE command, 72 
UCL, 20 

UCL command, 72 

UNLOAD c ommand, 73 

Unlocking a job from memory, 183 

UNPROTECT command, 72 

Unrecognizable command, 18 

USE command, 72 

User Command Interface, 17, 24 


TSXUCL program, 23 
Tuning parameters 


Break sentinel, 125 
Character echoing, 103 
Checking for activation, 128 
Checking for input errors, 127 
Command file input, 104 
Defining activation characters, 


103 

Disabling virtual line use, 103 
Echo control, 103 




SETSIZ 


A.2 Setting total allocation for a SAV file 

The "/T" switch is used to specify the total amount of memory space to be 
allocated for a program when it is run. The form of the /T switch is 
”/T:value." where "value" is the number of K-bytes of memory to allocate. 
Note that a decimal point must be specified with the value if it is entered as 
a decimal value. 

If the "/T" switch is used without a value, the effect is to clear the TSX-Plus 
size allocation information in the SAV file. 


Examples: 


.R SETSIZ 
*SY:PIP/T:18. 

*TSTPRG/T:32. 

* PR0G1/T 

A.3 Setting amount of dynamic memory space 

The "/D" switch is used to specify the amount of dynamic memory space to be 
reserved for a program. The SETSIZ program calculates the total amount of 
space to allocate for the program by adding the static size (stored in location 
50 of the SAV file by LINK) to the specified dynamic size. The form of the /D 
switch is "/D:value." where "value" is the number of K-bytes of dynamic memory 
space to reserve. If a program does not use any dynamic memory space, the /D 
switch may be used without an argument value to cause the total memory space 
allocation to be set equal to the static size of the program. FORTRAN programs 
use dynamic space for I/O buffers and the exact amount required depends on the 
number of 1/0 channels used. However, 4Kb of dynamic memory space seems to be 
adequate for most FORTRAN programs. 


Examples: 


.R SETSIZ 
*SY:PIP/D:11 
*TSTPRG/D:4. 
*PR0G1/D 




































